Merge branch 'main' of https://github.com/terminusdb/terminusdb-client-js

Author: Kitty Jose

docs/api/woqlclient.md

@@ -748,8 +748,10 @@ const response1 = await client.addDocument(json, {"graph_type": "schema"},
 ```
 
 ## queryDocument
-##### woqlClient.queryDocument(query, [params], [dbId], [branch], [lastDataVersion], [getDataVersion]) ⇒ <code>Promise</code>
-Retrieves all documents that match a given document template
+##### ~~woqlClient.queryDocument(query, [params], [dbId], [branch], [lastDataVersion], [getDataVersion]) ⇒ <code>Promise</code>~~
+***Deprecated***
+
+Use [#getDocument](#getDocument) instead.
 
 **Returns**: <code>Promise</code> - A promise that returns the call response object or object having *result*
 and *dataVersion* object if ***getDataVersion*** parameter is true, or an Error if rejected.  
@@ -808,7 +810,7 @@ console.log(response);
 ```
 
 ## getDocument
-##### woqlClient.getDocument([params], [dbId], [branch], [lastDataVersion], [getDataVersion]) ⇒ <code>Promise</code>
+##### woqlClient.getDocument([params], [dbId], [branch], [lastDataVersion], [getDataVersion], [query]) ⇒ <code>Promise</code>
 **Returns**: <code>Promise</code> - A promise that returns the call response object or object having *result*
 and *dataVersion* object if ***getDataVersion*** parameter is true, or an Error if rejected.  
 
@@ -819,6 +821,7 @@ and *dataVersion* object if ***getDataVersion*** parameter is true, or an Error
 | [branch] | <code>string</code> | the database branch |
 | [lastDataVersion] | <code>string</code> | the last data version tracking id. |
 | [getDataVersion] | <code>boolean</code> | If true the function will return object having result and dataVersion. |
+| [query] | <code>object</code> | If a query object is provided, the function will use it to query the database. |
 
 **Example**  
 ```javascript
@@ -856,7 +859,7 @@ const response1 = await client.getDocument({"graph_type":"schema","as_list":true
 ```
 
 ## updateDocument
-##### woqlClient.updateDocument(json, [params], [dbId], [message], [lastDataVersion], [getDataVersion]) ⇒ <code>Promise</code>
+##### woqlClient.updateDocument(json, [params], [dbId], [message], [lastDataVersion], [getDataVersion], [create]) ⇒ <code>Promise</code>
 **Returns**: <code>Promise</code> - A promise that returns the call response object or object having *result*
 and *dataVersion* object if ***getDataVersion*** parameter is true, or an Error if rejected.  
 
@@ -868,6 +871,7 @@ and *dataVersion* object if ***getDataVersion*** parameter is true, or an Error
 | [message] | <code>\*</code> | the update commit message |
 | [lastDataVersion] | <code>string</code> | the last data version tracking id. |
 | [getDataVersion] | <code>boolean</code> | If true the function will return object having result and dataVersion. |
+| [create] | <code>boolean</code> | If true, the function will create a new document if it doesn't exist. |
 
 **Example**  
 ```javascript

lib/query/woqlDoc.js

@@ -40,7 +40,7 @@ function convert(obj) {
       '@type': 'Value',
       variable: obj.name,
     };
-  } if (typeof (obj) === 'object') {
+  } if (typeof (obj) === 'object' && !Array.isArray(obj)) {
     const pairs = [];
     // eslint-disable-next-line no-restricted-syntax
     for (const [key, value] of Object.entries(obj)) {
@@ -57,6 +57,12 @@ function convert(obj) {
         data: pairs,
       },
     };
+  } if (typeof (obj) === 'object' && Array.isArray(obj)) {
+    const list = obj.map(convert);
+    return {
+      '@type': 'Value',
+      list,
+    };
   }
 }
 

lib/woqlClient.js

@@ -1012,6 +1012,9 @@ WOQLClient.prototype.addDocument = function (json, params, dbId, message = 'add
 };
 
 /**
+ * Use {@link #getDocument} instead.
+ * @deprecated
+ *
  * Retrieves all documents that match a given document template
  * @param {object} query - the query template
  * @param {typedef.DocParamsGet} [params] - the get parameters
@@ -1092,6 +1095,8 @@ WOQLClient.prototype.queryDocument = function (query, params, dbId, branch, last
  * @param {string} [lastDataVersion] the last data version tracking id.
  * @param {boolean} [getDataVersion] If true the function will return object having result
  * and dataVersion.
+ * @param {object} [query] If a query object is provided, the function will use it to
+ * query the database.
  * @returns {Promise}  A promise that returns the call response object or object having *result*
  * and *dataVersion* object if ***getDataVersion*** parameter is true, or an Error if rejected.
  * @example
@@ -1128,7 +1133,7 @@ WOQLClient.prototype.queryDocument = function (query, params, dbId, branch, last
  * )
  */
 // document interface
-WOQLClient.prototype.getDocument = function (params, dbId, branch, lastDataVersion = '', getDataVersion = false) {
+WOQLClient.prototype.getDocument = function (params, dbId, branch, lastDataVersion = '', getDataVersion = false, query = undefined) {
   if (dbId) {
     this.db(dbId);
   }
@@ -1138,6 +1143,16 @@ WOQLClient.prototype.getDocument = function (params, dbId, branch, lastDataVersi
   if (typeof lastDataVersion === 'string' && lastDataVersion !== '') {
     this.customHeaders({ 'TerminusDB-Data-Version': lastDataVersion });
   }
+
+  if (query) {
+    return this.dispatch(
+      CONST.QUERY_DOCUMENT,
+      this.connectionConfig.documentURL(params),
+      query,
+      getDataVersion,
+    );
+  }
+
   return this.dispatch(CONST.GET, this.connectionConfig.documentURL(params), {}, getDataVersion);
 };
 
@@ -1150,6 +1165,7 @@ WOQLClient.prototype.getDocument = function (params, dbId, branch, lastDataVersi
  * @param {string} [lastDataVersion] the last data version tracking id.
  * @param {boolean} [getDataVersion] If true the function will return object having result
  * and dataVersion.
+ * @param {boolean} [create] If true, the function will create a new document if it doesn't exist.
  * @returns {Promise}  A promise that returns the call response object or object having *result*
  * and *dataVersion* object if ***getDataVersion*** parameter is true, or an Error if rejected.
  * @example
@@ -1210,10 +1226,11 @@ WOQLClient.prototype.getDocument = function (params, dbId, branch, lastDataVersi
     );
  */
 
-WOQLClient.prototype.updateDocument = function (json, params, dbId, message = 'update document', lastDataVersion = '', getDataVersion = false, compress = false) {
+WOQLClient.prototype.updateDocument = function (json, params, dbId, message = 'update document', lastDataVersion = '', getDataVersion = false, compress = false, create = false) {
   const docParams = params || {};
   docParams.author = this.author();
   docParams.message = message;
+  docParams.create = create;
   if (dbId) {
     this.db(dbId);
   }