Lian

Simple object persistence for node.js with MongoDB.

tl;dr

I wanted something more involved than just a DB driver but I didn't want to define a schema or similar meta object.

I also only want to work with the objects I define - if I've saved a Person object, when I invoke a find operation it should return an array of Person objects.

Finally, writing tests for projects that use MongoDB should be easy and not rely on a connection to a DB instance.

See the other goals.

Examples

var lian = require('lian')('localhost/mydb');

function Person (name) {
    lian(this, 'person');
    this.name = name;
}

Person.prototype.getGender = function () {
    return this.gender;
}

var john = new Person('John Smith');
john.gender = "male";

john.save();

Create a projection of Person to find the instance saved above.

var john = new Person('John Smith');
john.find().then(function (results) {

    john = results[0];
    john.name; // "John Smith"
    john.getGender(); // "male"
});

Make some changes to persist.

john.name = "John Anthony Smith";
john.save();

Decoupled, lian's Store object can be used directly.

var lian  = require('lian'),
    Store = lian.Store;

function Person (name) {
    lian(this, 'person');
    this.name = name;
}

var steve = new Person('steve');

typeof steve.insert // "undefined"

var store = new Store('localhost/mydb');
store.insert(steve);

Easy to mock with, for testing. Require the lian/lib/mock module path instead of lian.

var lian = require('lian/lib/mock')('localhost/mydb');

function Person (name) {
    lian(this, 'person');
    this.name = name;
}

var john = new Person('John Smith');
john.gender = "male";

// saved in memory
john.save().then(function () {

    var john2 = new Person('John Smith');
    john2.findOne().then(function (result) {
        result.gender; // "male"
    });
});

Hooks for validation.

var lian = require('lian')('localhost/mydb');

function Person (name) {
    lian(this, 'person', {
        before: {
            'insert': function (person) {
                // check the person has a gender set
                return (person.gender);
            }
        }
    });

    this.name = name;
}

var john = new Person('John Smith');

john.insert().then(
    function () {
        // promise is rejected, see next callback
    },
    function () {
        throw new Error("failed to pass validation");
    }
);

Learn more about validation or read more documentation.

Goals

Avoid writing result to object mapping code over and over.
Instance based connections, multiple connections within the same process.
All asynchronous operations should return a promise.
Store provides an in-memory alternative, for testing.

Install

Install with npm.

npm install lian

Development

Lian uses monk to talk to MongoDB and promised-io for futures.

Clone the repo...

git clone git://github.com/richardhodgson/lian.git

Use npm to install dependencies.

cd lian && \
npm install --dev

Run the tests.

make test

The tests mock out monk, there are integration tests expecting a MongoDB instance running on localhost:27017. They will create a lian-integration database.

make integration-test