update docjs

Author: Francesca-Bit

lib/connectionCapabilities.js

@@ -62,14 +62,16 @@ ConnectionCapabilities.prototype.set_databases = function(newdbs) {
 ConnectionCapabilities.prototype.get_database = function(dbid, orgid) {
     if(!this.databases) this.databases = this._databases_from_dbdocs()
     for(var i = 0; i<this.databases.length; i++){
-        if(this.databases[i].id == dbid && this.databases[i].organization == orgid) return this.databases[i]
+        if(this.databases[i].id == dbid && this.databases[i].organization == orgid){
+            return this.databases[i]
+        }
     }
 }
 
 ConnectionCapabilities.prototype._databases_from_dbdocs = function() {
     let dbs = []
     for(var docid in this.dbdocs){
-        if(this.dbdocs[docid].system == false) {
+        if(this.dbdocs[docid].system === false) {
             dbs.push(this._get_db_rec(this.dbdocs[docid]))
         }
     }

lib/connectionConfig.js

@@ -1,17 +1,38 @@
+/**
+ * @typedef {type:'basic'|'jwt', user:string, key:string } CredentialObj
+ */
+
 /**
  * @file Terminus DB connection configuration
  * @license Apache Version 2
  * @description Object representing the state of a connection to a terminus db - these are:
- * 1. server url (set on connect)
- * 2. current organization id
- * 2. dbid, organization, api key, remote auth
- * along with some configuration information (key, connected mode, client_side_access_control)
+ * @constructor
+ * @param {string} serverUrl - the terminusdb server url
+ * @param {object | undefined} params - an object with the following connection parameters:
+ * @param {string}  params.key - api key for basic auth
+ * @param {string}  params.user - basic auth user id
+ * @param {string}  params.organization - set organization to this id
+ * @param {string}  params.db - set cursor to this db
+ * @param {?string} params.repo - set cursor to this repo
+ * @param {?string} params.branch - set branch to this id
+ * @param {?ref}    params.ref    - set commit ref 
+ * @param {?string} params.jwt - jwt token 
+ * @param {?string} params.jwt_user - jwt user id
+//KEVIN
+ * @param {?string} params.default_branch_id - set the default branch id 
  * provides methods for getting and setting connection parameters
  */
-function ConnectionConfig(serverUrl, params) {
+
+function ConnectionConfig(serverUrl, params=null) {
+    /** @type {string | boolean} */
     this.server = false
+    
+    /** @type {CredentialObj | boolean} */
     this.remote_auth = false //remote auth for authenticating to remote servers for push / fetch / clone
+    
+    /** @type {CredentialObj | boolean} */
     this.local_auth = false // basic auth string for authenticating to local server
+    
     //these operate as cursors - where within the connected server context, we currently are
     this.organizationid = false
     this.dbid = false
@@ -33,13 +54,15 @@ function ConnectionConfig(serverUrl, params) {
         this.server = surl
         if (params) this.update(params)
     } else {
+        //better throw an error
         this.setError(`Invalid Server URL: ${serverUrl}`)
     }
     //this.setServer(serverUrl);
 }
 
 /**
- * Creates a new connection config object and copies all the state information from this one into it
+ * @description Creates a new connection config object and copies all the state information from this one into it
+ * @returns {ConnectionConfig} 
  */
 ConnectionConfig.prototype.copy = function() {
     let other = new ConnectionConfig(this.server)
@@ -54,77 +77,133 @@ ConnectionConfig.prototype.copy = function() {
 }
 
 /**
- * updates connection config with new values set in json params object
+ * updates connection config with new parameters 
+ * @param {object}  params - an object with the following connection parameters:
+ * @param {string}  params.key - api key for basic auth
+ * @param {string}  params.user - basic auth user id
+ * @param {string}  params.organization - set organization to this id
+ * @param {string}  params.db - set cursor to this db
+ * @param {?string} params.repo - set cursor to this repo
+ * @param {?string} params.branch - set branch to this id
+ * @param {?ref}    params.ref    - set commit ref 
+ * @param {?string} params.jwt - jwt token 
+ * @param {?string} params.jwt_user - jwt user id
+/ 
  */
 ConnectionConfig.prototype.update = function(params) {
-    const newParams = params || {}
-    //if (typeof newParams.server != "undefined") this.setServer(newParams.server);
-    if (typeof newParams.organization != 'undefined') this.setOrganization(newParams.organization)
-    else if(newParams.user) this.setOrganization(newParams.user)
-    if (typeof newParams.db != 'undefined') this.setDB(newParams.db)
-    if (typeof newParams.remote_auth != 'undefined') this.setRemoteAuth(newParams.remote_auth)
-    if (typeof newParams.local_auth != 'undefined') this.setLocalAuth(newParams.local_auth)
-    if (typeof newParams.key != 'undefined') this.setLocalBasicAuth(newParams.key, newParams.user)
-    if (typeof newParams.branch != 'undefined') this.setBranch(newParams.branch)
-    if (typeof newParams.ref != 'undefined') this.setRef(newParams.ref)
-    if (typeof newParams.repo != 'undefined') this.setRepo(newParams.repo)
+    if(!params)return
+    if (typeof params.organization !== 'undefined') this.setOrganization(params.organization)
+    else if(params.user) this.setOrganization(params.user)
+    if (typeof params.db !== 'undefined') this.setDB(params.db)
+    //if (params.remote_auth !== undefined) this.setRemoteAuth(newParams.remote_auth)
+    //if (params.local_auth !== undefined) this.setLocalAuth(newParams.local_auth)
+    if (typeof params.key !== 'undefined') this.setLocalBasicAuth(params.key, params.user)
+    if (typeof params.branch !== 'undefined') this.setBranch(params.branch)
+    if (typeof params.ref !== 'undefined') this.setRef(params.ref)
+    if (typeof params.repo !== 'undefined') this.setRepo(params.repo)
 }
 
 /**
  * Simple gets to retrieve current connection status
+ * Gets the current server url
+ * @returns {string}
  */
 ConnectionConfig.prototype.serverURL = function() {
     return this.server
 }
 
 /**
- * Simple gets to retrieve current connection status
+ * @description Gets the server connection url
+ * @returns {string}
  */
 ConnectionConfig.prototype.apiURL = function() {
     return this.server + this.api_extension
 }
 
-
+/**
+ * @description Gets the current database id 
+ * @returns {string | boolean}
+ */
 ConnectionConfig.prototype.db = function() {
     return this.dbid
 }
 
+/**
+ * @description Gets the current branch id 
+ * @returns {string}
+ */
 ConnectionConfig.prototype.branch = function() {
     return this.branchid
 }
 
+/**
+ * @description Gets the current commit ref id 
+ * @returns {string | boolean}
+ */
 ConnectionConfig.prototype.ref = function() {
     return this.refid
 }
 
+/**
+ * @description Gets the current organization id 
+ * @returns {string | boolean}
+ */
 ConnectionConfig.prototype.organization = function() {
     return this.organizationid
 }
 
+
+/**
+ * @description Gets the current organization id 
+ * @returns {string}
+ */
 ConnectionConfig.prototype.repo = function() {
     return this.repoid
 }
 
+/**
+ *@description Gets the local Authorization credentials
+ *return {CredentialObj | boolean}
+ */
 ConnectionConfig.prototype.localAuth = function() {
     return this.local_auth
 }
 
+/**
+ *@description Gets the local user name
+ *return {string | boolean}
+ */
 ConnectionConfig.prototype.local_user = function() {
     if (this.local_auth) return this.local_auth.user
+    return false
 }
 
+/**
+ *@description Gets the remote Authorization credentials
+ *to connect the local db with a remote terminusdb database
+ *return {CredentialObj | boolean}
+ */
 ConnectionConfig.prototype.remoteAuth = function() {
     return this.remote_auth
 }
 
-ConnectionConfig.prototype.user = function(ignore_jwt) {
+/**
+ *@description Gets the current user name
+ *@param {boolean} ignoreJwt
+ *return {string}
+ */
+ConnectionConfig.prototype.user = function(ignoreJwt) {
     if (!ignore_jwt && this.remote_auth && this.remote_auth.type == 'jwt')
         return this.remote_auth.user
     if (this.local_auth) {
         return this.local_auth.user
     }
 }
 
+/**
+* @param 
+*/
+
 ConnectionConfig.prototype.parseServerURL = function(str) {
     if (str && (str.substring(0, 7) === 'http://' || str.substring(0, 8) === 'https://')) {
         if (str.lastIndexOf('/') !== str.length - 1) {
@@ -163,49 +242,66 @@ ConnectionConfig.prototype.setError = function(str) {
 }
 
 /**
- * @param {String} inputStr - organization to which the connected db belongs (not the users organization - set in capabilities)
+ * @description Set the organization to which the connected db belongs 
+ * (not the users organization - set in capabilities)
+ * @param {String} organization
+ * 
  */
-ConnectionConfig.prototype.setOrganization = function(inputStr) {
-    this.organizationid = inputStr || false
+ConnectionConfig.prototype.setOrganization = function(organization) {
+    this.organizationid = organization || false
     return this.organizationid
 }
 
 /**
- * @param {String} inputStr - local identifier of db
+ * @description Set the local identifier of db
+ * @param {string | boolean} db - database Id
+ //KEVIN we need that return ???
+ provably before you did a control but we don't need that return
+ * return {string | boolean}
  */
-ConnectionConfig.prototype.setDB = function(inputStr) {
-    this.dbid = inputStr
+ConnectionConfig.prototype.setDB = function(db) {
+    this.dbid = db
     return this.dbid
 }
 
 /**
- * @param {String} inputStr - local identifier of repo
+ * @typedef {"local"|"remote"} RepoType
  */
-ConnectionConfig.prototype.setRepo = function(inputStr) {
-    this.repoid = inputStr
+
+/**
+ * @description Set the repository type |local|remote|
+ * @param {RepoType} repo - for the local server - identifier of repo
+ */
+ConnectionConfig.prototype.setRepo = function(repo) {
+    this.repoid = repo
     return this.repoid
 }
 
 /**
- * @param {String} inputStr - id of branch
+ * @param {String | boolean} branch - id of branch
+ * @return {string}
  */
-ConnectionConfig.prototype.setBranch = function(inputStr) {
-    this.branchid = inputStr
+ConnectionConfig.prototype.setBranch = function(branch) {
+    this.branchid = branch
     if(!this.branchid) this.branchid = this.default_branch_id
     return this.branchid
 }
 
 /**
- * @param {String} inputStr - id of ref
+ * Set an Reference ID or Commit ID. 
+ * Commit IDs are unique hashes that are created whenever a new commit is recorded
+ * @param {string | boolean} refId - commit reference id
+ * @return {string | boolean}
  */
-ConnectionConfig.prototype.setRef = function(inputStr) {
-    this.refid = inputStr
+ConnectionConfig.prototype.setRef = function(refId) {
+    this.refid = refId
     return this.refid
 }
 
 /**
- * @param {String} userKey - api key
- * @param {String} userId - basic auth user id key
+ * @description set the local database connection credential 
+ * @param {?string} userKey - basic auth api key
+ * @param {?string} userId -  user id 
  */
 ConnectionConfig.prototype.setLocalBasicAuth = function(userKey, userId) {
     if (!userKey) {
@@ -219,8 +315,13 @@ ConnectionConfig.prototype.setLocalBasicAuth = function(userKey, userId) {
     }
 }
 
-ConnectionConfig.prototype.setLocalAuth = function(details) {
-    this.local_auth = details
+
+/**
+ * @description set the local database connection credential 
+ * @param {CredentialObj} newCredential 
+ */
+ConnectionConfig.prototype.setLocalAuth = function(newCredential) {
+    this.local_auth = newCredential
 }
 
 
@@ -395,8 +496,14 @@ ConnectionConfig.prototype.repoBase = function(action) {
     return b
 }
 
+
+ // @typedef {"keyvalue" | "bar" | "timeseries" | "pie" | "table"} ActionString
+ 
+
 /**
+ * @description Get database branch Url
  * Generate base branch url consisting of server/action/organization/dbid/branchid
+ * @param {string} action 
  */
 ConnectionConfig.prototype.branchBase = function(action) {
     let b = this.repoBase(action)
@@ -416,10 +523,12 @@ ConnectionConfig.prototype.branchBase = function(action) {
 }
 
 /**
- * Generate url portion consisting of organization/dbid (unless dbid = terminus in which case there is no organization)
+ * @description Generate url portion consisting of organization/dbid 
+ * (unless dbid = system dbname in which case there is no organization)
+ * @return {string}
  */
 ConnectionConfig.prototype.dbURLFragment = function() {
-    if (this.db() == this.system_db) return this.db()
+    if (this.db() === this.system_db) return this.db()
     return this.organization() + '/' + this.db()
 }
 

lib/dispatchRequest.js

@@ -47,12 +47,20 @@ function DispatchRequest(url, action, payload, local_auth, remote_auth = null) {
       options.httpsAgent = agent
     }
 
+    /*
+    * I can call the local database using the local authorization key or
+    * a jwt token
+    */
     if (local_auth && local_auth.type == 'basic') {
         let encoded = btoaImplementation(local_auth.user + ':' + local_auth.key)
         options.headers = {Authorization: `Basic ${encoded}`}
     } else if (local_auth && local_auth.type == 'jwt') {
         options.headers = {Authorization: `Bearer ${local_auth.key}`}
     }
+    /*
+    * pass the Authorization information of another 
+    * terminusdb server to the local terminusdb 
+    */
     if (remote_auth && remote_auth.type == 'jwt') {
         if (!options.headers) options.headers = {}
         options.headers['Authorization-Remote'] = `Bearer ${remote_auth.key}`