Merge pull request #121 from terminusdb/getDatabases

add getdatabases method  and review documentation

Author: Francesca-Bit

docs/_sidebar.md

@@ -18,10 +18,10 @@
     - [server](api/woqlClient.js?id=server)
     - [api](api/woqlClient.js?id=api)
     - [organization](api/woqlClient.js?id=organization)
+    - [getDatabases](api/woqlClient.js?id=getDatabases)
+    - [databases](api/woqlClient.js?id=databases)
     - [user](api/woqlClient.js?id=user)
     - [userOrganization](api/woqlClient.js?id=userOrganization)
-    - [databases](api/woqlClient.js?id=databases)
-    - [userOrganizations](api/woqlClient.js?id=userOrganizations)
     - [databaseInfo](api/woqlClient.js?id=databaseInfo)
     - [db](api/woqlClient.js?id=db)
     - [setSystemDb](api/woqlClient.js?id=setSystemDb)
@@ -58,6 +58,8 @@
     - [getEnums](api/woqlClient.js?id=getEnums)
     - [getClassDocuments](api/woqlClient.js?id=getClassDocuments)
     - [getBranches](api/woqlClient.js?id=getBranches)
+    - [getUserOrganizations](api/woqlClient.js?id=getUserOrganizations)
+    - [userOrganizations](api/woqlClient.js?id=userOrganizations)
     - [getDiff](api/woqlClient.js?id=getDiff)
     - [patch](api/woqlClient.js?id=patch)
 - [WOQL](api/woql.js?id=WOQL)

docs/api/woqlClient.js.md

@@ -32,6 +32,13 @@ const client = new TerminusClient.WOQLClient('SERVER_CLOUD_URL/mycloudTeam',
                      {user:"[email protected]", organization:'mycloudTeam'})
 
 client.setApiKey(MY_ACCESS_TOKEN)
+
+//to get the list of all organization's databases
+async function callGetDatabases(){
+     const dbList = await client.getDatabases()
+     console.log(dbList)
+}
+
 async function getSchema() {
      client.db("test")
      client.checkout("dev")
@@ -303,7 +310,8 @@ let api_url = client.api()
 
 ### organization
 #### woqlClient.organization([orgId]) ⇒ <code>string</code> \| <code>boolean</code>
-Gets/Sets the client’s internal organization context value
+Gets/Sets the client’s internal organization context value, if you change the organization name the 
+databases list will be set to empty
 
 
 | Param | Type | Description |
@@ -315,46 +323,49 @@ Gets/Sets the client’s internal organization context value
 client.organization("admin")
 ```
 
-### user
-#### woqlClient.user() ⇒ <code>Object</code>
-Gets the current user object as returned by the connect capabilities response
-user has fields: [id, name, notes, author]
+### getDatabases
+#### woqlClient.getDatabases() ⇒ <code>string</code> \| <code>boolean</code>
+Gets the organization's databases list.
 
+If no organization has been set up, the function throws an exception
 
-### userOrganization
-#### woqlClient.userOrganization() ⇒ <code>string</code>
-**Returns**: <code>string</code> - the user organization name  
-**Desription**: Gets the user's organization id  
+**Example**  
+```js
+async function callGetDatabases(){
+     const dbList = await client.getDatabases()
+     console.log(dbList)
+}
+```
 
 ### databases
 #### woqlClient.databases([dbList]) ⇒ <code>array</code>
-Retrieves a list of databases (id, organization, label, comment) that the current user has access to on the server.
+Set/Get the organization's databases list (id, label, comment) that the current user has access to on the server.
 
-**Returns**: <code>array</code> - the user databases list  
+**Returns**: <code>array</code> - the organization's databases list  
 
 | Param | Type | Description |
 | --- | --- | --- |
 | [dbList] | <code>array</code> | a list of databases the user has access to on the server, each having: |
 
 **Example**  
 ```js
-const my_dbs = client.databases()
+//to get the list of all organization's databases
+async function callGetDatabases(){
+     await client.getDatabases()
+     console.log(client.databases())
+}
 ```
 
-### userOrganizations
-#### woqlClient.userOrganizations([orgList]) ⇒ <code>array</code>
-Retrieves a list of databases (id, organization, label, comment) that the current user has access to on the server.
-
-**Returns**: <code>array</code> - the user databases list  
+### user
+#### woqlClient.user() ⇒ <code>Object</code>
+Gets the current user object as returned by the connect capabilities response
+user has fields: [id, name, notes, author]
 
-| Param | Type | Description |
-| --- | --- | --- |
-| [orgList] | <code>array</code> | a list of databases the user has access to on the server, each having: |
 
-**Example**  
-```js
-const my_dbs = client.databases()
-```
+### userOrganization
+#### woqlClient.userOrganization() ⇒ <code>string</code>
+**Returns**: <code>string</code> - the user organization name  
+**Desription**: Gets the user's organization id  
 
 ### databaseInfo
 #### woqlClient.databaseInfo([dbId]) ⇒ <code>object</code>
@@ -851,6 +862,37 @@ get the database collections list
 client.getBranches()
 ```
 
+### getUserOrganizations
+#### woqlClient.getUserOrganizations() ⇒ <code>Promise</code>
+Get the list of the user's organizations and the database related
+
+**Returns**: <code>Promise</code> - A promise that returns the call response object, or an Error if rejected.  
+**Example**  
+```js
+async funtion callGetUserOrganizations(){
+     await getUserOrganizations()
+     console.log(client.userOrganizations())
+}
+```
+
+### userOrganizations
+#### woqlClient.userOrganizations([orgList]) ⇒ <code>array</code>
+Get/Set the list of the user's organizations (id, organization, label, comment).
+
+**Returns**: <code>array</code> - the user Organizations list  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [orgList] | <code>array</code> | a list of user's Organization |
+
+**Example**  
+```js
+async funtion callGetUserOrganizations(){
+     await client.getUserOrganizations()
+     console.log(client.userOrganizations())
+}
+```
+
 ### getDiff
 #### woqlClient.getDiff(before, after) ⇒ <code>Promise</code>
 Get the patch of difference between two documents.

lib/connectionConfig.js

@@ -229,6 +229,11 @@ ConnectionConfig.prototype.serverUrlEncoding =  function(str){
     const orgArr = str.split("/")
     if(orgArr.length>3){
         //const org = encodeURI(orgArr[3])
+        /*
+        * if we pass the organization name like Francesca-Bit-9e73  
+        * I need to encode it 2 times because in the database 
+        * when we create an id from a property it encodes the property value
+        */
         const org = encodeURISegment(orgArr[3])
         return str.replace(orgArr[3], org)
     }
@@ -375,6 +380,8 @@ ConnectionConfig.prototype.userURL = function(user) {
 //encodeURIComponent
 ConnectionConfig.prototype.organizationURL = function(orgId, action) {
     let url = `${this.apiURL()}organization`
+    //I have to encode the organization 2 times because it is saved encoded inside the database
+    //
     if (orgId) url += `/${encodeURISegment(orgId)}`
     if (action) url += `/${encodeURISegment(action)}`
     return url

lib/woqlClient.js

@@ -34,6 +34,13 @@ const { default: axios } = require('axios')
  *                      {user:"myemail@something.com", organization:'mycloudTeam'})
  *                                           
  * client.setApiKey(MY_ACCESS_TOKEN)
+ * 
+ * //to get the list of all organization's databases
+ * async function callGetDatabases(){
+ *      const dbList = await client.getDatabases()
+ *      console.log(dbList)
+ * }
+ * 
  * async function getSchema() {
  *      client.db("test")
  *      client.checkout("dev")
@@ -109,23 +116,64 @@ WOQLClient.prototype.api = function() {
 }
 
 /**
- * Gets/Sets the client’s internal organization context value
+ * Gets/Sets the client’s internal organization context value, if you change the organization name the 
+ * databases list will be set to empty
  * @param {string | boolean} [orgId] the organization id to set the context to
  * @returns {string | boolean}
  * @example
  * client.organization("admin")
  */
 WOQLClient.prototype.organization = function(orgId) {
     if (typeof orgId !== 'undefined') {
-        this.connectionConfig.setOrganization(orgId)  
-        const orgObj =  this.userOrganizations().find(element => element['name'] === orgId)  
-        const dbs = orgObj ? orgObj.databases : []
-        //change the database list
-        this.databases(dbs)
+        this.connectionConfig.setOrganization(orgId)
+        //we have to reset the databases list 
+        this.databases([])
     }
     return this.connectionConfig.organization()
 }
 
+/**
+ * Gets the organization's databases list.
+ * 
+ * If no organization has been set up, the function throws an exception
+ * @returns {string | boolean}
+ * @example
+ * async function callGetDatabases(){
+ *      const dbList = await client.getDatabases()
+ *      console.log(dbList)
+ * }
+ */
+WOQLClient.prototype.getDatabases = async function(){
+    // return response
+    if(!this.connectionConfig.organization()){
+        throw new Error(`You need to set the organization name`);
+    }
+    //when we will have the end point to get the databases only for the current organization 
+    //we'll change this call
+    await this.getUserOrganizations();
+    const dbs =  this.userOrganizations().find(element => element['name'] === this.connectionConfig.organization()) 
+    const dbList = dbs && dbs.databases ? dbs.databases : []
+    this.databases(dbList)
+    return dbList
+}
+
+/**
+ * Set/Get the organization's databases list (id, label, comment) that the current user has access to on the server.
+ * @param {array} [dbList] a list of databases the user has access to on the server, each having:
+ * @returns {array} the organization's databases list
+ * @example
+ * //to get the list of all organization's databases
+ * async function callGetDatabases(){
+ *      await client.getDatabases()
+ *      console.log(client.databases())
+ * }
+ * 
+ */
+ WOQLClient.prototype.databases = function(dbList) {
+    if (dbList) this.databaseList = dbList
+    return this.databaseList || []
+}
+
 /**
  * Gets the current user object as returned by the connect capabilities response
  * user has fields: [id, name, notes, author]
@@ -146,32 +194,6 @@ WOQLClient.prototype.userOrganization = function() {
 }
 
 
-/**
- * Retrieves a list of databases (id, organization, label, comment) that the current user has access to on the server.
- * @param {array} [dbList] a list of databases the user has access to on the server, each having:
- * @returns {array} the user databases list
- * @example
- * const my_dbs = client.databases()
- */
-WOQLClient.prototype.databases = function(dbList) {
-    if (dbList) this.databaseList = dbList
-    return this.databaseList || []
-}
-
-/**
- * Retrieves a list of databases (id, organization, label, comment) that the current user has access to on the server.
- * @param {array} [orgList] a list of databases the user has access to on the server, each having:
- * @returns {array} the user databases list
- * @example
- * const my_dbs = client.databases()
- */
- WOQLClient.prototype.userOrganizations = function(orgList) {
-    if (orgList) this.organizationList = orgList
-    return this.organizationList || []
-}
-
-
-
 /**
  * Gets the database's details
  * @param {string} [dbId] - the datbase id
@@ -196,8 +218,6 @@ WOQLClient.prototype.db = function(dbId) {
         this.connectionConfig.setDB(dbId)
     }
     return this.connectionConfig.dbid
-    
-    //this.connectionConfig.db()
 }
 
 /**
@@ -821,22 +841,6 @@ WOQLClient.prototype.prepareRevisionControlArgs = function(rc_args) {
 
 
 
-/***
- * Server Version API
- * Note: the below endpoints are not part of the terminusdb desktop package
- * they belong to the server package version of the DB which is under construction.
- * Until that package is released all of the below endpoints should be considered
- * as unreliable and subject to change - they are provided complete with the desktop
- * version to show users what is coming and to allow people to use them at their own risk
- * Any use of them should be considered unsupported and at your own risk
- *  get all the database information from the remote server
- * @returns {Promise}  A promise that returns the call response object, or an Error if rejected.
- */
-
-WOQLClient.prototype.getDatabase = function() {
-    return this.dispatch(CONST.GET, this.connectionConfig.dbURL())
-}
-
 /**
  *  update the database details
  * @param {object} dbDoc - an object that describe the database details
@@ -1071,42 +1075,45 @@ WOQLClient.prototype.getBranches = function(dbId){
         this.checkout(branch)
         return branchesObj
     })
-    //reset branch
-   
+    //reset branch   
 }
 
-//this method is not documented
-/*
- * get the organizations and the database related
- * @param {string} [defaultOrg] - the organizatation to set 
+/**
+ * Get the list of the user's organizations and the database related
  * @returns {Promise}  A promise that returns the call response object, or an Error if rejected. 
  * @example
- * client.getUserOrganizations()
+ * async funtion callGetUserOrganizations(){
+ *      await getUserOrganizations()
+ *      console.log(client.userOrganizations())
+ * }
  */
- WOQLClient.prototype.getUserOrganizations = function(defaultOrg){
-     //this.databases(response)
-     // return response
+ WOQLClient.prototype.getUserOrganizations = function(){
+    // this will be change to give back only the organizations list
     return this.dispatch(
         CONST.GET,
         this.connectionConfig.userOrganizationsURL(),
     ).then(response => {   
         const orgList = Array.isArray(response) ? response : []
         this.userOrganizations(orgList)
-        if (orgList.length>0){          
-            let orgObj
-            if(defaultOrg){
-                orgObj = orgList.find(element => element['name'] === defaultOrg)               
-            }
-            //if I didn't find the default one I get the first result
-            if (!orgObj){
-                orgObj = orgList[0]
-            }
-            this.organization(orgObj['name'])  
-        } 
         return orgList
     })
 }
 
+/**
+ * Get/Set the list of the user's organizations (id, organization, label, comment).
+ * @param {array} [orgList] a list of user's Organization
+ * @returns {array} the user Organizations list
+ * @example
+ * async funtion callGetUserOrganizations(){
+ *      await client.getUserOrganizations()
+ *      console.log(client.userOrganizations())
+ * }
+ */
+ WOQLClient.prototype.userOrganizations = function(orgList) {
+    if (orgList) this.organizationList = orgList
+    return this.organizationList || []
+}
+
 /**
  * Get the patch of difference between two documents.
  * @param {object} before - The current state of JSON document