API is not ergonomic

Moved from GitHub dgraph-js/62

Posted by felixfbecker:

It seems like the API is purely a generated gRPC client. This makes it very unergonomic for JavaScript in many places:

  • None of the classes have constructors. For example, I can’t pass the value directly to new Value(), instead I have to call value.setStringVal('abc'). One would expect an API more around object literals rather than getter and setter methods
  • The API allows contradictory state. For example, what happens when I call both setStringVal() and setIntVal()?
  • Some methods are confusingly named - e.g. setSetJson()
  • There are no docblocks on any methods
  • Some types are completely unclear how to use - e.g. setGeoVal() takes a string or a UInt8Array.

campoy commented :

Hi @felixfbecker,

It is true this is a pretty thin layer built on top of the autogenerated gRPC code.
We are currently growing our teams to be able to have the bandwidth to improve all of our clients (and also provide new ones).

We will keep this issue open and track improvements, feel free to send more issues if you see other specific parts of the API that should definitely be fixed.


zakmandhro commented :

@felixfbecker If you are looking for a higher level of abstraction for Dgraph, you may want to check out GitHub - gverse/gverse: A modern TypeScript/JavaScript Object Graph Mapper for the Dgraph Graph Database, an open-source Object-Graph Mapper for Dgraph. It is built on dgraph-js.

Gverse allows you to define vertices as classes:

const graph = new Gverse.Graph(
  new Gverse.Connection({ host: "localhost", port: 9080 })

class User extends Gverse.Vertex {
  type = "User"
  name: string

and then query, mutate, etc. with ease:

const user = new User()
user.name = "Zak"
await graph.create(User)

Gverse also provides a friendlier API for connections, transactions, relationships (edges), marshaling/unmarshaling, querying, mutating, etc. You can see the usage details in the integration tests.

I built Gverse for my startups and we are using it on multiple products. We’d love your feedback and contributions.

campoy commented :

Wow, that’s a great project @zakmandhro!

@hackintoshrao, could you make sure we add this to our docs on the part of unofficial clients?

Also, we should definitely send a t-shirt to @zakmandhro for the amazing work. Please send me an email with you address to francesc@dgraph.io and I’ll make sure you receive one.

Thanks @campoy! Dgraph is a great open source project. I’m happy to contribute to the ecosystem.

I’ll get in touch for the coveted t-shirt. :blush:


Hey! Can you drop a mail to fulsmita@dgraph.io ? Tagging @fulsmita.