review typescript declarations (#265)

* review typescript declarations

---------

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

Author: Francesca-Bit

docs/api/typedef.md

@@ -47,6 +47,7 @@ the PUT document interface query parameters
 | Name | Type | Description |
 | --- | --- | --- |
 | [raw_json] | <code>boolean</code> | 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. |
+| [create] | <code>boolean</code> | If true, the function will create  a new document if it doesn't exist. |
 | [graph_type] | <code>GraphType</code> | default is instance, instance|schema Used to switch between  getting documents from the instance or the schema graph. |
 
 
@@ -60,7 +61,7 @@ the DELETE document interface query parameters
 | --- | --- | --- |
 | [graph_type] | <code>GraphType</code> | default is instance, instance|schema Used to switch between  getting documents from the instance or the schema graph. |
 | id | <code>string</code> \| <code>array</code> | a single id or a list of ids to delete. |
-| [nuke] | <code>booleam</code> | default is false, If true, delete everything at this resource  location (dangerous!). |
+| [nuke] | <code>boolean</code> | default is false, If true, delete everything at this resource  location (dangerous!). |
 
 
 ## GraphRef

docs/api/woql.md

@@ -1455,8 +1455,10 @@ const doc = WOQL.doc({ "@type": "Person", name: "Newperson" })
 ```
 
 ## client
-##### WOQL.client(client) ⇒ <code>WOQLClient</code>
-Gets/Sets woqlClient
+##### ~~WOQL.client(client) ⇒ <code>WOQLClient</code>~~
+***Deprecated***
+
+Use instead to run your query woqlclient.query('myWOQLQuery')
 
 
 | Param | Type |

docs/api/woqlclient.md

@@ -55,11 +55,8 @@ async function getSchema() {
 ##### ~~woqlClient.connect([params]) ⇒ <code>Promise</code>~~
 ***Deprecated***
 
-Connect to a Terminus server at the given URI with an API key
-Stores the system:ServerCapability document returned
-in the connection register which stores, the url, key, capabilities,
-and database meta-data for the connected server
-this.connectionConfig.server will be used if present,
+You can call this to get the server info or override the start params
+configuration, this.connectionConfig.server will be used if present,
 or the promise will be rejected.
 
 **Returns**: <code>Promise</code> - the connection capabilities response object or an error object  
@@ -863,8 +860,8 @@ client.getDocument({"graph_type":"schema","as_list":true,"id":"Country"}).then(r
 })
 
 //pass a document query template to query the document interface
-const queryTemplate = { "name": "Ireland", "@type":"Country" }
-client.getDocument({"graph_type":"schema","as_list":true,
+const queryTemplate = { "name": "Ireland"}
+client.getDocument({"as_list":true, "@type":"Country"
            query:queryTemplate}).then(result=>{
    console.log(result)
 })
@@ -968,6 +965,17 @@ const response1 = await client.updateDocument(
       "",
       response.dataVersion
     );
+
+ // update a document and create the linked document together
+ // we are update the document "Person/Person01"
+ // and create a new document {"@type": "Person","name": "child01"} at the same time
+ const response1 = await client.updateDocument(
+     {
+      "@id": "Person/Person01",
+      "@type": "Person",
+      "name": "Person01"
+      "children":[{"@type": "Person","name": "child01"}]
+    },{create:true})
 ```
 
 ## deleteDocument

lib/connectionConfig.js

@@ -1,6 +1,8 @@
 /// /@ts-check
 // connectionConfig
 const { encodeURISegment } = require('./utils');
+// eslint-disable-next-line no-unused-vars
+const typedef = require('./typedef');
 
 /**
  * @file Terminus DB connection configuration

lib/dispatchRequest.js

@@ -5,6 +5,8 @@ const UTILS = require('./utils');
 const CONST = require('./const');
 const ErrorMessage = require('./errorMessage');
 const { version } = require('../package.json');
+// eslint-disable-next-line no-unused-vars
+const typedef = require('./typedef');
 /**
  * base 64 encodes a string using either the btoa implementation if available or the Buffer object.
  * @param {String} str string to be base 64 encoded
@@ -64,9 +66,12 @@ function checkPayload(payload, options, compress) {
  * @param {string} url  API endpoint URL
  * @param {string} action API action
  * @param {object} payload data to be transmitted to endpoint
- * @param {string} key optional basic auth string to be passed
- * @param {object} customHeaders the unique reqID
- * @param {boolean} compress If true, compress the data with gzip if its size is bigger than 1024
+ * @param {typedef.CredentialObj} local_auth the local authorization object
+ * @param {typedef.CredentialObj} remote_auth the remote authoriuzation object
+ * @param {object} customHeaders all the custom header to add to your call
+ * @param {boolean} [getDataVersion] If true the function will return object having result
+ * and dataVersion.
+ * @param {boolean} [compress] If true, compress the data with gzip if its size is bigger than 1024
  */
 
 // eslint-disable-next-line max-len

lib/query/woqlBuilder.js

@@ -20,6 +20,9 @@
  */
 
 const WOQLQueryExt = require('./woqlQuery');
+
+// eslint-disable-next-line no-unused-vars
+const typedef = require('../typedef');
 // const WOQLLibrary = require('./woqlLibrary');
 
 class WOQLQuery extends WOQLQueryExt {
@@ -114,17 +117,17 @@ WOQLQuery.prototype.iri = function (s) {
  * @returns {WOQLQuery} A WOQLQuery which contains the a Update Triple Statement
  */
 
-WOQLQuery.prototype.update_triple = function (subject, predicate, new_object, old_object) {
-  const tmp_name = old_object || `v:AnyObject__${this.counter += 1}`;
+WOQLQuery.prototype.update_triple = function (subject, predicate, newObjValue, oldObjValue) {
+  const tmp_name = oldObjValue || `v:AnyObject__${this.counter += 1}`;
   return this.and(
     new WOQLQuery().opt(
       new WOQLQuery()
         .triple(subject, predicate, tmp_name)
         .delete_triple(subject, predicate, tmp_name)
         .not()
-        .triple(subject, predicate, new_object),
+        .triple(subject, predicate, newObjValue),
     ),
-    new WOQLQuery().add_triple(subject, predicate, new_object),
+    new WOQLQuery().add_triple(subject, predicate, newObjValue),
   );
 };
 
@@ -139,17 +142,17 @@ WOQLQuery.prototype.update_triple = function (subject, predicate, new_object, ol
  * @returns {WOQLQuery} A WOQLQuery which contains the a Update Quad Statement
  */
 
-WOQLQuery.prototype.update_quad = function (subject, predicate, new_object, graph) {
+WOQLQuery.prototype.update_quad = function (subject, predicate, newObject, graph) {
   const tmp_name = `v:AnyObject__${this.counter += 1}`;
   return this.and(
     new WOQLQuery().opt(
       new WOQLQuery()
         .quad(subject, predicate, tmp_name, graph)
         .delete_quad(subject, predicate, tmp_name, graph)
         .not()
-        .quad(subject, predicate, new_object, graph),
+        .quad(subject, predicate, newObject, graph),
     ),
-    new WOQLQuery().add_quad(subject, predicate, new_object, graph),
+    new WOQLQuery().add_quad(subject, predicate, newObject, graph),
   );
 };
 
@@ -199,9 +202,9 @@ WOQLQuery.prototype.node = function (node, type) {
  * be used for subsequent chained schema calls
  * @returns {WOQLQuery} A WOQLQuery which contains the partial Graph pattern matching expression
  */
-WOQLQuery.prototype.graph = function (g) {
+WOQLQuery.prototype.graph = function (graphRef) {
   return this._set_context({
-    graph: g,
+    graph: graphRef,
   });
 };
 // do not remove

lib/query/woqlCore.js

@@ -16,6 +16,9 @@ const UTILS = require('../utils');
 const WOQLPrinter = require('./woqlPrinter');
 const { Var, Vars, Doc } = require('./woqlDoc');
 
+// eslint-disable-next-line no-unused-vars
+const typedef = require('../typedef');
+
 /**
  * defines the internal functions of the woql query object - the
  * language API is defined in WOQLQuery
@@ -596,6 +599,8 @@ WOQLQuery.prototype.getVocabulary = function (vocab) {
 };
 
 /**
+ * Use instead woqlclient.query('myWOQLQuery')
+ * @deprecated
  * Executes the query using the passed client to connect to a server
  *
  */

lib/query/woqlQuery.js

@@ -10,6 +10,7 @@
 /* eslint-disable prefer-destructuring */
 /* eslint-disable guard-for-in */
 /* eslint-disable no-restricted-syntax */
+
 /// /@ts-check
 // WOQLQuery
 /**
@@ -23,6 +24,8 @@
 
 const WOQLCore = require('./woqlCore');
 const { Var, Vars, Doc } = require('./woqlDoc');
+// eslint-disable-next-line no-unused-vars
+const typedef = require('../typedef');
 
 // I HAVE TO REVIEW THE Inheritance and the prototype chain
 class WOQLQuery extends WOQLCore {
@@ -390,7 +393,7 @@ WOQLQuery.prototype.and = function (...subqueries) {
 
 /**
  * Creates a logical OR of the arguments
- * @param {...WOQLQuery} [subqueries] - A list of one or more woql queries
+ * @param {...WOQLQuery} subqueries - A list of one or more woql queries
  * to execute as alternatives
  * @returns {WOQLQuery} - A WOQLQuery object containing the logical Or of the subqueries
  */

lib/typedef.js

@@ -45,6 +45,8 @@ const { ACTIONS } = Utils.ACTIONS;
  *@property {boolean} [raw_json] - 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.
+ *@property {boolean} [create] - If true, the function will create
+ a new document if it doesn't exist.
  *@property {GraphType} [graph_type] - default is instance, instance|schema Used to switch between
  getting documents from the instance or the schema graph.
  */
@@ -54,7 +56,7 @@ const { ACTIONS } = Utils.ACTIONS;
  *@property {GraphType} [graph_type] - default is instance, instance|schema Used to switch between
  getting documents from the instance or the schema graph.
  *@property {string|array} id - a single id or a list of ids to delete.
- *@property {booleam} [nuke] - default is false, If true, delete everything at this resource
+ *@property {boolean} [nuke] - default is false, If true, delete everything at this resource
  location (dangerous!).
  */
 

lib/woql.js

@@ -5,6 +5,11 @@
 const WOQLQuery = require('./query/woqlBuilder');
 const WOQLLibrary = require('./query/woqlLibrary');
 const { Vars, Var, Doc } = require('./query/woqlDoc');
+// eslint-disable-next-line no-unused-vars
+const typedef = require('./typedef');
+// eslint-disable-next-line no-unused-vars
+const WOQLClient = require('./woqlClient');
+
 /**
  * @license Apache Version 2
  * @module WOQL
@@ -1359,6 +1364,8 @@ WOQL.doc = function (object) {
 };
 
 /**
+ * Use instead to run your query woqlclient.query('myWOQLQuery')
+ * @deprecated
  * Gets/Sets woqlClient
  * @param {WOQLClient}
  * @returns {WOQLClient}