From ba2e09b2ed193cecc43c654672b317dc7b3654c2 Mon Sep 17 00:00:00 2001 From: Francesca-Bit Date: Tue, 23 Aug 2022 16:54:32 +0200 Subject: [PATCH 1/5] review diff method and add apply --- lib/connectionConfig.js | 9 +++ lib/woqlClient.js | 134 ++++++++++++++++++++++++++++++---------- 2 files changed, 112 insertions(+), 31 deletions(-) diff --git a/lib/connectionConfig.js b/lib/connectionConfig.js index e22c1814..fc64502a 100644 --- a/lib/connectionConfig.js +++ b/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 diff --git a/lib/woqlClient.js b/lib/woqlClient.js index f462b194..4f9a0b9a 100644 --- a/lib/woqlClient.js +++ b/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.getDiff( * { "@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'; @@ -1497,18 +1504,19 @@ WOQLClient.prototype.getDiff = function (before, after, options) { /** * 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 {object} after - The updated state of JSON document - * @param {object} options [{}] - Options to send to the diff endpoint + * @param {string} before - The version from which to compare the object + * @param {object} afterVersion - The updated state of JSON document + * @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(jsonObj, "a73ssscfx0kke7z76083cgswszdxy6l").then(diffResp=>{ + * console.log(diffResp) + * }) */ -WOQLClient.prototype.getVersionObjectDiff = function (id, beforeVersion, after, options) { +WOQLClient.prototype.getVersionObjectDiff = function (jsonObject, dataVersion, id, 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'; @@ -1516,10 +1524,15 @@ WOQLClient.prototype.getVersionObjectDiff = function (id, beforeVersion, after, 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, + before: jsonObject, + after_data_version: dataVersion, + ...opt, }; + if (id) { + payload.id = id; + } return this.dispatch( CONST.POST, this.connectionConfig.diffURL(), @@ -1528,34 +1541,58 @@ 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(), @@ -1563,6 +1600,41 @@ WOQLClient.prototype.getVersionDiff = function (id, beforeVersion, afterVersion, ).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 From 9d7a12e00e200aaf706f565fb8cacaa0e6e8b57e Mon Sep 17 00:00:00 2001 From: Francesca-Bit Date: Tue, 23 Aug 2022 16:54:57 +0200 Subject: [PATCH 2/5] review diff method and add apply --- .eslintignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.eslintignore b/.eslintignore index de1ca4c8..366e3ebc 100644 --- a/.eslintignore +++ b/.eslintignore @@ -8,3 +8,4 @@ package-lock.json .nyc_output test/ tutorial/ +local_test/ From 53296e3f52e0f7c124cf2a552381dd9677530f08 Mon Sep 17 00:00:00 2001 From: Francesca-Bit Date: Tue, 23 Aug 2022 17:59:21 +0200 Subject: [PATCH 3/5] review documentation --- lib/woqlClient.js | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/lib/woqlClient.js b/lib/woqlClient.js index 4f9a0b9a..92a2e9cb 100644 --- a/lib/woqlClient.js +++ b/lib/woqlClient.js @@ -1473,7 +1473,7 @@ WOQLClient.prototype.userOrganizations = function (orgList) { * 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 - * client.getDiff( + * client.getJSONDiff( * { "@id": "Person/Jane", "@type": "Person", name: "Jane" }, * { "@id": "Person/Jane", "@type": "Person", name: "Janine" } * ).then(diffResult=>{ @@ -1503,22 +1503,23 @@ WOQLClient.prototype.getJSONDiff = 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} before - The version from which to compare the object - * @param {object} afterVersion - The updated state of JSON document * @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 jsonObj = { "@id": "Person/Jane", "@type": "Person", name: "Janine" } - * client.getVersionObjectDiff(jsonObj, "a73ssscfx0kke7z76083cgswszdxy6l").then(diffResp=>{ + * client.getVersionObjectDiff("main",jsonObj + * "Person/Jane").then(diffResp=>{ * console.log(diffResp) * }) */ -WOQLClient.prototype.getVersionObjectDiff = function (jsonObject, dataVersion, id, 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)), @@ -1526,8 +1527,8 @@ WOQLClient.prototype.getVersionObjectDiff = function (jsonObject, dataVersion, i } const opt = options || {}; const payload = { - before: jsonObject, - after_data_version: dataVersion, + after: jsonObject, + before_data_version: dataVersion, ...opt, }; if (id) { From f33a8656a25f21c6bf9c84fe5cc319005ca5c4b9 Mon Sep 17 00:00:00 2001 From: Francesca-Bit Date: Wed, 24 Aug 2022 15:51:43 +0200 Subject: [PATCH 4/5] review docs --- README.md | 2 +- lib/woqlClient.js | 14 ++++++-------- 2 files changed, 7 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index b8d463fd..532d76b1 100644 --- a/README.md +++ b/README.md @@ -100,7 +100,7 @@ const bankerSchema = [ "@type":"Class", "@id":"Person", "@key":{ - "@type":"Hash", + "@type":"Lexical", "@fields":[ "name" ] diff --git a/lib/woqlClient.js b/lib/woqlClient.js index 92a2e9cb..c9529d89 100644 --- a/lib/woqlClient.js +++ b/lib/woqlClient.js @@ -208,13 +208,13 @@ WOQLClient.prototype.userOrganization = function () { /** * Gets the database's details - * @param {string} [dbId] - the datbase id - * @returns {object} the database description object //getDatabaseInfo + * @param {string} [dbName] - the datbase name + * @returns {object} the database description object */ -WOQLClient.prototype.databaseInfo = function (dbId) { +WOQLClient.prototype.databaseInfo = function (dbName) { // const dbIdVal = dbId || this.db(); // const orgIdVal = orgId || this.organization() - const database = this.databases().find((element) => element.name === dbId); + const database = this.databases().find((element) => element.name === dbName); return database || {}; }; @@ -1518,7 +1518,7 @@ WOQLClient.prototype.getJSONDiff = function (before, after, options) { * }) */ WOQLClient.prototype.getVersionObjectDiff = function (dataVersion, jsonObject, id, options) { - if (typeof jsonObject !== 'object' || typeof dataVersion !== 'string') { + if (typeof jsonObject !== 'object' || typeof dataVersion !== 'string' || typeof id !== 'string') { const errmsg = 'Parameters error - you must specify a valid jsonObject document and valid branch or commit'; return Promise.reject( @@ -1529,11 +1529,9 @@ WOQLClient.prototype.getVersionObjectDiff = function (dataVersion, jsonObject, i const payload = { after: jsonObject, before_data_version: dataVersion, + id, ...opt, }; - if (id) { - payload.id = id; - } return this.dispatch( CONST.POST, this.connectionConfig.diffURL(), From c593ec83cf0738727c8ac469f86d261b3f793540 Mon Sep 17 00:00:00 2001 From: Francesca-Bit Date: Wed, 24 Aug 2022 13:53:15 +0000 Subject: [PATCH 5/5] Apply docs changes --- docs/api/typedef.md | 2 + docs/api/woqlclient.md | 105 +++++++++++++++++++++++++++++------------ 2 files changed, 77 insertions(+), 30 deletions(-) diff --git a/docs/api/typedef.md b/docs/api/typedef.md index e9b5973d..e8f8d628 100644 --- a/docs/api/typedef.md +++ b/docs/api/typedef.md @@ -32,6 +32,7 @@ the POST document interface query parameters | Name | Type | Description | | --- | --- | --- | +| [raw_json] | boolean | default is false, If true, the input documents are treated as raw JSON, inserted as type sys:JSONDocument and are not subject to schema restrictions. | | [graph_type] | GraphType | default is instance instance|schema Used to switch between getting documents from the instance or the schema graph. | | [full_replace] | boolean | default is false, If true, all existing documents are deleted before inserting the posted documents. This allows the full replacement of the contents of a database. This is especially useful for replacing the schema. | @@ -44,6 +45,7 @@ the PUT document interface query parameters | Name | Type | Description | | --- | --- | --- | +| [raw_json] | boolean | default is false, If true, the input documents are treated as raw JSON, inserted as type sys:JSONDocument and are not subject to schema restrictions. | | [graph_type] | GraphType | default is instance, instance|schema Used to switch between getting documents from the instance or the schema graph. | diff --git a/docs/api/woqlclient.md b/docs/api/woqlclient.md index bffe86b2..96737759 100644 --- a/docs/api/woqlclient.md +++ b/docs/api/woqlclient.md @@ -384,14 +384,14 @@ user has fields: [id, name, notes, author] **Desription**: Gets the user's organization id ## databaseInfo -##### woqlClient.databaseInfo([dbId]) ⇒ object +##### woqlClient.databaseInfo([dbName]) ⇒ object Gets the database's details -**Returns**: object - the database description object //getDatabaseInfo +**Returns**: object - the database description object | Param | Type | Description | | --- | --- | --- | -| [dbId] | string | the datbase id | +| [dbName] | string | the datbase name | ## db @@ -699,7 +699,7 @@ and *dataVersion* object if ***getDataVersion*** parameter is true, or an Error | Param | Type | Description | | --- | --- | --- | | json | object | | -| [params] | typedef.DocParamsPost | the post parameters | +| [params] | typedef.DocParamsPost | the post parameters [#typedef.DocParamsPost](#typedef.DocParamsPost) | | [dbId] | string | the dbid | | [string] | message | the insert commit message | | [lastDataVersion] | string | the last data version tracking id. | @@ -866,7 +866,7 @@ and *dataVersion* object if ***getDataVersion*** parameter is true, or an Error | Param | Type | Description | | --- | --- | --- | | json | object | | -| [params] | typedef.DocParamsPut | the Put parameters | +| [params] | typedef.DocParamsPut | the Put parameters [#typedef.DocParamsPut](#typedef.DocParamsPut) | | [dbId] | \* | the database id | | [message] | \* | the update commit message | | [lastDataVersion] | string | the last data version tracking id. | @@ -1122,8 +1122,8 @@ async funtion callGetUserOrganizations(){ } ``` -## getDiff -##### woqlClient.getDiff(before, after, options) ⇒ Promise +## getJSONDiff +##### woqlClient.getJSONDiff(before, after, [options]) ⇒ Promise Get the patch of difference between two documents. **Returns**: Promise - 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 | object | The current state of JSON document | | after | object | The updated state of JSON document | -| options | object | [{}] - Options to send to the diff endpoint | +| [options] | object | {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) ⇒ Promise +##### woqlClient.getVersionObjectDiff(dataVersion, jsonObject, id, [options]) ⇒ Promise Get the patch of difference between two documents. **Returns**: Promise - A promise that returns the call response object, or an Error if rejected. | Param | Type | Description | | --- | --- | --- | +| dataVersion | string | The version from which to compare the object | +| jsonObject | object | The updated state of JSON document | | id | string | The object id to be diffed | -| beforeVersion | string | The version from which to compare the object | -| after | object | The updated state of JSON document | -| options | object | [{}] - Options to send to the diff endpoint | +| [options] | object | {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) ⇒ Promise -Get the patch of difference between two documents. +##### woqlClient.getVersionDiff(beforeVersion, afterVersion, [id], [options]) ⇒ Promise +Get the patch of difference between branches or commits. **Returns**: Promise - A promise that returns the call response object, or an Error if rejected. | Param | Type | Description | | --- | --- | --- | -| id | string | The object id to be diffed | -| beforeVersion | string | The version from which to compare the object | -| afterVersion | string | The version to which to compare the object | -| options | object | [{}] - Options to send to the diff endpoint | +| beforeVersion | string | Before branch/commit to compare | +| afterVersion | string | Before branch/commit to compare | +| [id] | string | The object id to be diffed, if it is omitted all the documents will be compared | +| [options] | object | {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 | string | Before branch/commit to compare | +| afterVersion | string | Before branch/commit to compare | +| message | string | apply commit message | +| [match_final_state] | boolean | the deafult value is false | +| [options] | object | {keep:{}} Options to send to the apply endpoint | + +**Example** +```javascript +client.checkout("mybranch") +client.apply("main","mybranch").then(result=>{ + console.log(result) +}) ``` ## patch