Viceroy

Control your empire

Battlefy introduces Viceroy. An ORM to rule over your data. Viceroy uses 'middleware' to connect models to data sources. Middleware allows Viceroy to read and write to many different types of databases. Middleware can also allow data filtering and analytics.

Viceroy Supports hasOne and hasMany relationships, easing the noSQL experience and allowing to you work on what you care about rather than accessing your data.

Getting started

Using Viceroy is easy. Lets get you familiar with the library and how to use it. We'll go through a few key examples of how to connect to your database, define a model, and interact with your database. In this example we will be using a mongo database via the viceroy-mongo middleware.

Connecting to your Database

Viceroy uses middleware to connect to databases. Currently mongo is the only supported database, however Redis, and Postgres are planned. We would also like to encurage others to author middleware for Viceroy, so feel free. If you do author your own middleware, please let us know so we can add it to our list.

Below we will pass our database information to viceroy mongo and connect to the database.

// Require viceroy and viceroy-mongo.
var viceroy = require('viceroy');
var viceroyMongo = require('viceroy-mongo');

// Provide viceroy with a configured instance of
// viceroy-mongo.
viceroy.use(viceroyMongo({
  host: 'viceroy.com',
  port: 8567,
  database: 'viceroy'
}));

// TODO: Register some models here.

// Attempt to connect to the database.
viceroy.connect(function(err) {
  if(err) { throw err; }

  // Note: we are now connected to the database.
  // At this point we could read and write to the
  // database, however we don't have any models
  // so lets look at defining those.

});

Creating your First Model

In order to work with our database we need models to abstract our data. Viceroy models are fun to work with and come with a few nice conveniences.

Below we will create a contact model with a schema and some relationships. Then wee will register the model with viceroy so it can read and write to the database.

// ...

// Require the util module.
var util = require('util');

// ...

// Reference a shorthand for viceroy.Model.
var Model = viceroy.Model;

// Define a contact model that inherits from
// model.
function Contact(data) {

  // setup the instance
  Model.apply(this, arguments);

  // define a schema
  this.addSchema({
    name: {
      first: String,
      last: String
    },
    birthday: {
      day: Number,
      month: Number,
      year: Number
    }
  });

  // define some relations.
  this.hasMany('Contact', 'friends');
  this.hasMany('Contact', 'colleges');
  this.hasOne('Contact', 'mother');
  this.hasOne('Contact', 'father');

}
util.inherits(Contact, Model);

// register the model with viceroy
viceroy.model(Contact);

// ...

Reading and Writing to the database

Now that we have a connection, and we know how to author our own models, lets try creating a contact and saving it to the database. We will also query our database for all contacts born in the year 1985, then delete them.

Once registered with viceroy, model classes are outfitted with several static methods, and will update the database when save or remove is called.

// ...

// retrieve our contact model.
var Contact = viceroy.model('Contact');

// create a new contact
var robert = new Contact({
  name: {
    first: 'Robert',
    last: 'Hurst'
  },
  birthdate: {
    day: 28,
    month: 1,
    year: 1990
  }
});

// save it to the database
robert.save(function(err) {

  // Because Viceroy updates models upon save,
  // we now have an id for our new contact.
  robert._id;

});

// remove everyone born in 1985
Contact.find({ 'birthdate.year': 1985 }, function(err, contacts) {
  if(err) { throw err; }
  contacts.remove(function(err) {
    if(err) { throw err; }
  });
});

All Together

If we take the code above and put it all together it looks like this.

// Require util, viceroy, and viceroy-mongo.
var util = require('util');
var viceroy = require('viceroy');
var viceroyMongo = require('viceroy-mongo');

// Reference a shorthand for viceroy.Model.
var Model = viceroy.Model;

// Provide viceroy with a configured instance of
// viceroy-mongo.
viceroy.use(viceroyMongo({
  host: 'viceroy.com',
  port: 8567,
  database: 'viceroy'
}));

// Define a contact model that inherits from
// model.
function Contact(data) {

  // setup the instance
  Model.call(this, data);

  // define a schema
  this.schema({
    name: {
      first: String,
      last: String
    },
    birthday: {
      day: Number,
      month: Number,
      year: Number
    }
  });

  // define some relations.
  this.hasMany('Contact', 'friends');
  this.hasMany('Contact', 'colleges');
  this.hasOne('Contact', 'mother');
  this.hasOne('Contact', 'father');

}
util.inherits(Contact, Model);

// register the model with viceroy
viceroy.model(Contact);

// Attempt to connect to the database.
viceroy.connect(function(err) {
  if(err) { throw err; }

  // create a new contact
  var robert = new Contact({
    name: {
      first: 'Robert',
      last: 'Hurst'
    },
    birthdate: {
      day: 28,
      month: 1,
      year: 1990
    }
  });

  // save it to the database
  robert.save(function(err) {

    // Because Viceroy updates models upon save,
    // we now have an id for our new contact.
    robert._id;

  });

  // remove everyone born in 1985
  Contact.find({ 'birthdate.year': 1985 }, function(err, contacts) {
    if(err) { throw err; }
    contacts.remove(function(err) {
      if(err) { throw err; }
    });
  });

});

Docs

please stand by...

Creating Middleware

Middleware must return the following object to viceroy.use.

{
  find: function(query, opts, callback) {},
  insert: function(query, opts, callback) {},
  update: function(query, delta, opts, callback) {},
  remove: function(query, opts, callback) {}
}