ArangoDB Object Modeling for Node.js, Foxx and Modern Web Browsers

Orango is an ODM (Object Data Modeler), an ORM (Object Relational Mapper) and an OGM (Object Graphical Mapper) in one that provides the following features:

• Central connectivity to ArangoDB
• Automated creation of collections and indexes
• Create schemas for data
• Interact with models to handle data-centric functionality
• Pre-populate database
• Graph linking and querying
• and more...

Why use Orango with ArangoDB?

• Ease of use
• Model-driven data
• Focus on data instead of queries
• Optimized query creation
• Validation
• Filter unknown data from being injected into database
• Cleaner interfaces
• Single point of change for bug fixes, features, etc
• Save on redundancy - DRY implementation
• Default values
• and more...

Community Support

Documentation & Articles

Official documentation can be found at orango.js.org. (This is a work in progress)

I will be regularly posting articles on CodeBurst.io (Medium). Follow me there https://codeburst.io/@roboncode

Follow me on Twitter https://twitter.com/@roboncode for updates

Installation

First be sure you have ArangoDB and Node.js installed. You can install ArangoDB using the official docker container.

Next, install Orango from the command line using npm:

$ npm install orango

Importing

// Using Node.js `require()`
const orango = require('orango')

// Using ES6 imports
import orango from 'orango'

Overview

Connecting to ArangoDB

First, we need to define a connection. If your app uses the default _system database, you can connect using orango.connect(). If you need to create additional connections, use orango.get( database:String ).connect().

The method connect([{url:String="http://localhost:8529", username:String, password:String}]) takes database name with options to establish a connection. Otherwise, it will use the default values.

const orango = require('orango')
const { EVENTS } = orango.consts

orango.events.once(EVENTS.CONNECTED, conn => {
   console.log('🥑  Connected to ArangoDB:', conn.url + '/' + conn.name)
})

orango.events.once(EVENTS.READY, () => {
   console.log('🍊  Orango is ready!')
})

async function main() {
   await orango.connect()
}

main()

Note: Orango buffers model definitions, so they can be defined before or after a connection is established.

Defining a Model

const schema = new orango.Schema({
  author: String,
  title: String,
  body: String,
  date: Date
})

orango.model('Blog', schema)

Aside from defining the structure of your documents and data types, Orango models can handle the definition of:

• Validators
• Default values
• Indexes
• Static methods
• Computed properties
• Hooks
• Custom queries
• Unknown property filters
• JSON to model structures
• Joi definitions

The following example shows some of these features:

const Joi = require('joi')
const { SCHEMA } = orango.consts
  
class UserSchema extends orango.Schema {
  // computed properties
  get fullName() {
    return (this.firstName + ' ' + this.lastName).trim()
  }
}

let schema = new UserSchema({
  firstName: String,
  lastName: String,
  // Joi can be used directly
  email: Joi.string().email(),
  // JSON gets converted to Joi data types automatically
  age: { type: Number, min: 18 },
  bio: { type: String, regex: /[a-z]/ },
  // default values are supported on insert and update
  created: { type: Date, default: Date.now },
  updated: { type: Date, defaultOnUpdate: Date.now }
})

schema.addIndex(SCHEMA.INDEX.HASH, 'email')
schema.addIndex(SCHEMA.INDEX.SKIP_LIST, ['firstName', 'lastName'])

let User = orango.model('User', schema)

// extend your model with custom functions
User.findByEmail = async function(email) {
  return await this.find().one().where({ email })
}

In code somewhere else

const User = orango.model('User')

...

let user = await User.findByEmail('john.smith@gmail.com').return({ model: true })
console.log('Hello,', user.name) // access model getter

Examples

A growing set of examples are available here. To run the examples, clone this project and then run the Orango docker containers.

Install dependencies

npm install

Run the docker containers provided by Orango

Linux and Mac

Run the ArangoDB containers provided by Orango.

$ make dbs

Windows

$ cd docker & docker-compose up -d

Run examples

npm run examples

You will be presented with a wizard where you can run different examples files.

Debugging the examples with VSCode

Setup your config like the example below. You can launch any number of the snippets by placing the snippet you would like to start in the args array. Then run the debugger. The output will be in the Debug Console.

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Count",
      "program": "${workspaceFolder}/examples/debug.js",
      "args": ["count"]
    },
    {
      "type": "node",
      "request": "launch",
      "name": "Find First",
      "program": "${workspaceFolder}/examples/debug.js",
      "args": ["find_first"]
    }
  ]
}

License

MIT

Copyright (c) 2018-present, Rob Taylor