resolve review comments

Author: shivaji-kharse

README.md

@@ -51,24 +51,38 @@ of using the Dgraph JavaScript client. Follow the instructions in the README of
 
 ### Creating a Client
 
-A `DgraphClient` object can be initialised by passing it a list of `DgraphClientStub` clients as
-variadic arguments. Connecting to multiple Dgraph servers in the same cluster allows for better
-distribution of workload.
+#### Connection Strings
 
-The following code snippet shows just one connection.
+The dgraph-js supports connecting to a Dgraph cluster using connection strings. Dgraph connections
+strings take the form `dgraph://{username:password@}host:port?args`.
 
-```js
-const dgraph = require("dgraph-js")
-const grpc = require("@grpc/grpc-js")
-
-const clientStub = new dgraph.DgraphClientStub(
-  // addr: optional, default: "localhost:9080"
-  "localhost:9080",
-  // credentials: optional, default: grpc.credentials.createInsecure()
-  grpc.credentials.createInsecure(),
-)
-const dgraphClient = new dgraph.DgraphClient(clientStub)
-```
+`username` and `password` are optional. If username is provided, a password must also be present. If
+supplied, these credentials are used to log into a Dgraph cluster through the ACL mechanism.
+
+Valid connection string args:
+
+| Arg         | Value                           | Description                                                                                                                                                   |
+| ----------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| apikey      | \<key\>                         | a Dgraph Cloud API Key                                                                                                                                        |
+| bearertoken | \<token\>                       | an access token                                                                                                                                               |
+| sslmode     | disable \| require \| verify-ca | TLS option, the default is `disable`. If `verify-ca` is set, the TLS certificate configured in the Dgraph cluster must be from a valid certificate authority. |
+
+## Some example connection strings: | Value | Explanation | |
+
+| ----------------------------------------------------------------------------------- | |
+dgraph://localhost:9080 | Connect to localhost, no ACL, no TLS | |
+dgraph://sally:supersecret@dg.example.com:443?sslmode=verify-ca | Connect to remote server, use ACL
+and require TLS and a valid certificate from a CA | |
+dgraph://foo-bar.grpc.us-west-2.aws.cloud.dgraph.io:443?sslmode=verify-ca&apikey=\<your-api-connection-key\>
+| Connect to a Dgraph Cloud cluster | |
+dgraph://foo-bar.grpc.hypermode.com?sslmode=verify-ca&bearertoken=\<some access token\> | Connect to
+a Dgraph cluster protected by a secure gateway |
+
+Using the `Open` function with a connection string: // open a connection to an ACL-enabled, non-TLS
+cluster and login as groot const {client,closeStub} =
+dgraph.Open("dgraph://groot:password@localhost:8090")
+
+````
 
 To facilitate debugging, [debug mode](#debug-mode) can be enabled for a client.
 
@@ -83,31 +97,12 @@ In order to create a JavaScript client, and make the client login into namespace
 ```js
 const dgraphClientStub = new dgraph.DgraphClientStub("localhost:9080")
 await dgraphClientStub.loginIntoNamespace("groot", "password", 123) // where 123 is the namespaceId
-```
+````
 
 In the example above, the client logs into namespace `123` using username `groot` and password
 `password`. Once logged in, the client can perform all the operations allowed to the `groot` user of
 namespace `123`.
 
-### Creating a Client for Dgraph Cloud Endpoint
-
-If you want to connect to Dgraph running on your [Dgraph Cloud](https://cloud.dgraph.io) instance,
-then all you need is the URL of your Dgraph Cloud endpoint and the API key. You can get a client
-using them as follows:
-
-```js
-const dgraph = require("dgraph-js")
-
-const clientStub = dgraph.clientStubFromCloudEndpoint(
-  "https://frozen-mango.eu-central-1.aws.cloud.dgraph.io/graphql",
-  "<api-key>",
-)
-const dgraphClient = new dgraph.DgraphClient(clientStub)
-```
-
-**Note:** the `clientStubFromSlashGraphQLEndpoint` method is deprecated and will be removed in the
-next release. Instead use `clientStubFromCloudEndpoint` method.
-
 ### Altering the Database
 
 To set the schema, create an `Operation` object, set the schema and pass it to
@@ -376,27 +371,21 @@ try {
 
 ### Cleanup Resources
 
-To cleanup resources, you have to call `DgraphClientStub#close()` individually for all the instances
-of `DgraphClientStub`.
+To cleanup resources, you have to call `close()`.
 
 ```js
 const SERVER_ADDR = "localhost:9080"
 const SERVER_CREDENTIALS = grpc.credentials.createInsecure()
 
-// Create instances of DgraphClientStub.
-const stub1 = new dgraph.DgraphClientStub(SERVER_ADDR, SERVER_CREDENTIALS)
-const stub2 = new dgraph.DgraphClientStub(SERVER_ADDR, SERVER_CREDENTIALS)
-
-// Create an instance of DgraphClient.
-const dgraphClient = new dgraph.DgraphClient(stub1, stub2)
+// Create instances of DgraphClient.
+const { client, closeStub } = dgraph.Open("dgraph://groot:password@${SERVER_ADDR}")
 
 // ...
 // Use dgraphClient
 // ...
 
-// Cleanup resources by closing all client stubs.
-stub1.close()
-stub2.close()
+// Cleanup resources by closing client stubs.
+closeStub()
 ```
 
 ### Debug mode

examples/simple/index.js

@@ -125,8 +125,7 @@ async function queryData(dgraphClient) {
 }
 
 async function main() {
-  const dgraphClientStub = newClientStub()
-  const dgraphClient = newClient(dgraphClientStub)
+  const { dgraphClient, closeStub } = dgraph.Open()
   await dropAll(dgraphClient)
   await setSchema(dgraphClient)
   await createData(dgraphClient)
@@ -137,7 +136,7 @@ async function main() {
   await queryData(dgraphClient)
 
   // Close the client stub.
-  dgraphClientStub.close()
+  closeStub()
 }
 
 main()

src/client.ts

@@ -4,8 +4,6 @@
  */
 
 import * as grpc from "@grpc/grpc-js"
-import * as url from "url"
-import * as querystring from "querystring"
 
 import * as messages from "../generated/api_pb"
 
@@ -159,9 +157,10 @@ function addBearerTokenToCredentials(
   return grpc.credentials.combineChannelCredentials(baseCreds, metaCreds)
 }
 
-export async function Open(connStr: string): Promise<DgraphClient> {
-  const parsedUrl = url.parse(connStr)
-
+export async function Open(
+  connStr: string,
+): Promise<{ client: DgraphClient; closeStub: () => void }> {
+  const parsedUrl = new URL(connStr)
   if (parsedUrl.protocol !== dgraphScheme) {
     throw new Error("Invalid scheme: must start with dgraph://")
   }
@@ -175,11 +174,11 @@ export async function Open(connStr: string): Promise<DgraphClient> {
     throw new Error("Invalid connection string: port required")
   }
 
+  // Parse query parameters using searchParams
   const queryParams: Record<string, string> = {}
-  if (parsedUrl.query) {
-    const parsedQuery = querystring.parse(parsedUrl.query)
-    Object.entries(parsedQuery).forEach(([key, value]) => {
-      queryParams[key] = Array.isArray(value) ? value[0] : value
+  if (parsedUrl.searchParams) {
+    parsedUrl.searchParams.forEach((value, key) => {
+      queryParams[key] = value
     })
   }
 
@@ -218,18 +217,20 @@ export async function Open(connStr: string): Promise<DgraphClient> {
 
   const clientStub = new DgraphClientStub(`${host}:${port}`, credentials)
 
-  if (parsedUrl.auth) {
-    const [username, password] = parsedUrl.auth.split(":")
-    if (!password) {
+  if (parsedUrl.username != "") {
+    if (parsedUrl.password === "") {
       throw new Error("Invalid connection string: password required when username is provided")
-    }
-
-    try {
-      await clientStub.login(username, password)
-    } catch (err) {
-      throw new Error(`Failed to sign in user: ${err.message}`)
+    } else {
+      try {
+        await clientStub.login(parsedUrl.username, parsedUrl.password)
+      } catch (err) {
+        throw new Error(`Failed to sign in user: ${err.message}`)
+      }
     }
   }
 
-  return new DgraphClient(clientStub)
+  return {
+    client: new DgraphClient(clientStub),
+    closeStub: () => clientStub.close(),
+  }
 }

src/clientStubFromSlash.ts

@@ -17,6 +17,10 @@ export function clientStubFromSlashGraphQLEndpoint(graphqlEndpoint: string, apiK
   return clientStubFromCloudEndpoint(graphqlEndpoint, apiKey)
 }
 
+/**
+ * @deprecated
+ *     Please use {@link Open} instead.
+ */
 export function clientStubFromCloudEndpoint(graphqlEndpoint: string, apiKey: string) {
   const url = new Url(graphqlEndpoint)
   const urlParts = url.host.split(".")

tests/integration/connect.spec.ts

@@ -10,7 +10,7 @@ import { SERVER_ADDR } from "../helper"
 describe("open function", () => {
   it("should connect with authentication and execute a query", async () => {
     const url = `dgraph://groot:password@${SERVER_ADDR}`
-    const client = await dgraph.Open(url)
+    const { client, closeStub } = await dgraph.Open(url)
     const query = `
       {
         me(func: uid(1)) {
@@ -25,6 +25,7 @@ describe("open function", () => {
     expect(response).not.toBeNull()
     const parsedJson = response.getJson() // No need for JSON.parse
     expect(parsedJson.me[0].uid).toBe("0x1")
+    closeStub()
   })
 
   it("should throw an error for invalid scheme", async () => {
@@ -35,14 +36,12 @@ describe("open function", () => {
   })
 
   it("should throw an error for missing hostname", async () => {
-    const invalidUrl = `dgraph://:${SERVER_ADDR.split(":")[1]}`
-    await expect(async () => dgraph.Open(invalidUrl)).rejects.toThrowError(
-      "Invalid connection string: hostname required",
-    )
+    const invalidUrl = `dgraph://:9081`
+    await expect(async () => dgraph.Open(invalidUrl)).rejects.toThrowError("Invalid URL")
   })
 
   it("should throw an error for missing port", async () => {
-    const invalidUrl = `dgraph://${SERVER_ADDR.split(":")[0]}`
+    const invalidUrl = `dgraph://localhost`
     await expect(async () => await dgraph.Open(invalidUrl)).rejects.toThrowError(
       "Invalid connection string: port required",
     )