Gverse

Note: This project is looking for maintainers. If you're interested, please create an issue. 🙏

#### Object Graph Mapper for Dgraph

!GitHub !CircleCI !npm type definitions !GitHub package.json version

Gverse is an Object Graph Mapper (OGM) for the Dgraph, the high-performance open-source Graph Database. Gverse is written in TypeScript and supports TypeScript 3 and JavaScript ES6.

#### What's an OGM?

An OGM enables developers to work with their graph models through idiomatic objects provided by their native programming language. It is similar in concept to Object-Relational Mapping (ORM) libraries such as TypeORM, Sequelize or Hibernate. See Gverse vs ORMs).

#### Features

- Simple API for working with graphs vertices (nodes) and edges (links)
- Strongly typed classes and predicates (attributes) when using TypeScript
- Automatically marshal and unmarshal JavaScript objects to and from Graph vertices
- Support for custom marshaling and unmarshaling methods
- Support for directed and undirected edges
- Support for transactions and batch updates
- Before and after hooks for create, update and delete operations
- Query options for ordering and pagination

##### Compatibility with Dgraph

The current version of Gverse supports Dgraph version 1.2.x.

For compatibility with Dgraph 1.0.x, use Gverse version 1.0.2. You can specify the version in your packages.json.

$3

Here's a quick start guide to get you up and running.

#### Install Dgraph

Make sure you have Dgraph installed and running. This guide assumes you have Dgraph running on default ports (8080 for HTTP and 9080 gRPC).

#### Set up your TypeScript or JavaScript ES6 environments

Gverse requires ES6 with class properties plugin or TypeScript ≥ 2.0.

- Configure your project for TypeScript (see getting started guide),
– or –
- Configure Babel (see quick start guide) and add the Class Properties Plugin.

#### Install the Gverse package

``sh
npm install gverse
`

or if you prefer, yarn add gverse. The package includes TypeScript types.

#### Create a Gverse graph session

`typescript
import Gverse from "gverse"

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

#### Defining the Dgraph-types for vertices

`typescript
const indices =
name: string @index(exact) @lang .
owner: [uid] .
repos: [uid] .
contributors: [uid] .
repositories: [uid] .

const types =
type User {
name
repositories
}
type Repository {
name
contributors
owner
}

await graph.applySchema(indices + types)
`

#### Define a vertex class

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

#### Create the vertex on the graph

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

#### Load a vertex from the graph

`typescript
const user = (await graph.get(uid)) as User
console.log(user.name) // = "Zak"
`

For detailed examples, please see the integration tests under ./test/integration.

#### Defining edges (links to other vertices)

`typescript
class Repo {
type: "Repository"
name: string
owner: User
contributors: User[]
_edges: {
owner: Edge.toVertex(User),
contributors: Edge.toVertices(User)
}
}
`

Edges can be directed or undirected (reversible), and can have a cardinality of one or many. For detailed examples, please see the integration tests under ./test/integration.

#### Running upsert (query with mutation)

The graph.newTransaction().upsert method enables you to execute upsert block having a query and a mutation:

`typescript
const query = {vertex as var(func: eq(name,"John"))}
const values = {
uid: "uid(vertex)",
name: "Smith"
}
await graph.newTransaction().upsert(query, values)
`

An optional parameter condition can be used to run a conditional upsert:

`typescript
const condition = eq(len(vertex), 1)
await graph.newTransaction().upsert(query, values, condition)
`

$3

Test coverage for Gverse comes from integration tests. Docker and Docker-Compose are required for running integration tests.

`sh
./run-integration-tests.sh
``

#### Gverse OGM vs Traditional ORMs

Gverse has some fundamental differences to popular ORMs. It's helpful to understand the key differences:

- Gverse works with vertices and edges in a Graph structure instead of tables, columns and rows in RDBMS like MySQL, Postgres, Oracle, or documents in MongoDB, CouchDB, etc. (learn more).
- Gverse schema supports dynamic typing. You do not need to define and migrate schemas. Predicates (attributes) can be added as needed, with their data types inferred by value.
- A schema definition is required for any type that is part of a query or filter function. Both the type and the index needs to be defined and applied. .
- Advanced graph queries in Gverse are written using GraphQL± (a variant of GraphQL).