Orcha

Orcha (pronounced "or-ka") is an object data mapping layer, (like mongoose.js) built on top of orchestrate.io's orchestrate.js library.

Please Note! This module is still in very early development and is only in the "readme-driven-development" phase. Please do not attempt to use this module, but watch this space until you can!

Why should you care?

If you've decided to use Orchestrate.io in one of your projects, and noticed that you are encountering any number of these problems, then Orcha is for you:

• constantly passing in API keys to authenticate with Orchestrate.io
• repeated validation logic in controllers
• scattered helper methods defined in different controllers for the same resource

By providing a "schema"-based API, Orcha offers you the tools to define singleton "Model" objects with a "schema" definition - the schema runs basic validation operations like checking that required properties exist, checking if a property on a key in a collection is unique and different from the same property on other instances of keys in that collection and performing type checking to see if a property has the correct data type, as well as allowing you to define default values for properties on a key.

Additionally, Orcha offers a middleware layer that allows you to define custom validation logic directly on the model, as well as custom static and instance methods, computed properties and before/after hooks.

With these tools in place, your code will be much cleaner and follow a more robust separation of concerns, because you will be able to easily extract all of this logic out of your controllers and the models can be easily reused.

Installation

Open up your project in a terminal, and

$ npm install orcha --save

Usage

Connecting to Orchestrate

var orcha = require('orcha');
 
// the string here is your Orchestrate app's API key
orcha.connect('i5j1ta21-saxj-6r9i-1wd8-x7rl8zsls9i2');

---

Creating a Model

var orcha = require('orcha');
 
var UserSchema = new orcha.Schema({
  name: 'string',
  email: {
    type: 'string',
    required: true,
    validate: {
      isEmail: true
    }
  },
  createdAt: {
    type: 'date',
    default: Date.now()
  }
});
 
module.exports = orcha.model('User', UserSchema);

---

Querying with Orcha

Creating a Key

User.create({
  // properties of this user
})
  .then(function(user) {
    // do something with newly created user
  })
  .fail(function(error) {
    // could not create user
  })

Fetching a Key

User.get(key)
  .then(function(user) {
    // do something with user
  });
  .fail(function(error) {
    // could not get user
  })

Updating a Key

User.update(key, {
  // properties to update
})
  .then(function(user) {
    // updated user
  })
  .fail(function(error) {
    // could not update user
 
  })

Update, if fail then Create

User.updateOrCreate(key, {
  // properties to update AND all other properties are required
})
  .then(function(user) {
    // updated/created user
  })
  .fail(function(error) {
    // could not update or create user
  });

Delete / Hard Delete

// removes the user from orchestrate, but previous versions will still persist
User.remove(key)
  .then(function() {
 
  })
  .fail(function(error) {
 
  });
 
// removes the user from orchestrate, and removes all previous versions along
// with it
User.remove(key, { purge: true })
  .then(function() {
 
  })
  .fail(function(error) {
 
  });

Listing all versions of a key

User.versions(key)
  .then(function(allVersionsOfThisUser) {
 
  })
  .fail(function(error) {
 
  });

Fetching a specific version of a key

User.version(key, version)
  .then(function(user) {
    // do something with this version of the user
  })
  .fail(function(error) {
 
  });

Listing all items in a collection

// `options` is an object that represents sort and filter options
// e.g. { limit: 10, offset: 10, startKey: 'c' }
User.listAll(options)
  .then(function(users) {
 
  })
  .fail(function(error) {
 
  });

Deleting an entire collection

User.removeAll()
  .then(function() {
 
  })
  .fail(function(error) {
 
  });

Searching for items in a collection

// `options` is an object that represents sort and filter options
// e.g. { limit: 10, offset: 10, startKey: 'c' }
User.search(query, [options])
  .then(function(result) {
 
  })
  .fail(function(error) {
 
  })

Still to Be Documented:

• Graph Relationships
• Events
• Geolocation

---

Defining Methods

Static and Instance methods allow you to create custom query logic for your models.

Static Methods

Static methods allow you to define query logic on the model:

UserSchema.statics.findByRole = function(role) {
  return this.search(role);
};
 
var User = orcha.model('User', UserSchema);
 
User.findByRole('admin')
  .then(function(users) {
    console.log(users);
  });

Instance Methods

Instance methods allow you to define query logic on an instance of a model:

UserSchema.methods.getFriends = function() {
  return this.model('User').retrieve('friends').from(this.key);
};
 
var User = orcha.model('User', UserSchema);
 
var bob = new User({
  name: 'Bob',
  email: '[e-mail]'
});
 
bob.getFriends()
  .then(function(friends) {
    console.log(friends);
  });

---

Adding Validation

Orcha provides a validate object property on each property of all schemas. In this object, you may specify any one of validator.js' validations like so:

var UserSchema = new orcha.Schema({
  name: {
    type: 'string',
    required: true,
    unique: true,
    validate: {
      isLength: [3, 12] // name must be between 3 and 12 characters long
    }
  },
  password: {
    type: 'string',
    required: true,
    validate: {
      isLength: 8 // password must be at least 8 characters long
    }
  }
});

As you can see, you may pass in either one argument or an array of arguments to be passed to the validator function.

There are two additional methods of defining validation rules. You can define them on the schema:

UserSchema.validator.isNumeric = function(value, [args...]) {
  return !!isNaN(value);
};
UserSchema.validate('id', isNumeric, [args...]);

Or as an Orcha globally accessible validator:

orcha.validator('isNumeric', function(value, [args...]) {
  return !!isNaN(value);
});
 
// you can then use this validator in any schema like this:
UserSchema.validate('id', orcha.validator('isNumeric'), [args...]);
 
// or directly in the schema definition, like this:
var UserSchema = new orcha.Schema({
  id: {
    type: 'number',
    validate: {
      isNumeric: true
    }
  }
});

---

Before/After Hooks

Still to be documented

Plugins

Still to be documented

How To Contribute to Orcha

Please read the Contribution Guidelines

License

The MIT License (MIT)

Copyright (c) 2014 io digital

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.