Nondeterministic Polynomial Munchies
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    viceroypublic

    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) {}
    }

    Keywords

    none

    install

    npm i viceroy

    Downloadslast 7 days

    0

    version

    1.5.20

    license

    MIT

    last publish

    collaborators

    • avatar
    • avatar