Iridium

A High Performance, IDE Friendly ODM for MongoDB

Iridium is designed to offer a high performance, easy to use and above all, editor friendly ODM for MongoDB on Node.js. Rather than adopting the "re-implement everything" approach often favoured by ODMs like Mongoose and friends, requiring you to learn an entirely new API and locking you into a specific coding style, Iridium tries to offer an incredibly lightweight implementation which makes your life easier where it counts and gets out of your way when you want to do anything more complex.

It also means that, if you're familiar with the MongoDB CLI you should find working with Iridium very natural, with all database methods returning promises for their results and sensible, type annotated results being provided if you wish to make use of them.

Installation

Iridium makes use of the latest set of @types TypeScript definitions files, allowing you to install everything using just a simple npm install.

npm install iridium --save

Features

• Built with TypeScript and designed for ease of use, you'll be hard pressed to find another Node.js ORM as easy to pick up and learn when combined with a supporting editor.
• Promises Throughout mean that you can easily start working with your favourite A+ compliant promise library and writing more readable code. Don't think promises are the way forward? Stick with callbacks, Iridium supports both.
• Fully Tested with over 300 unit tests and over 95% test coverage, helping to ensure that Iridium always behaves the way it's supposed to.
• Decorator Support helps describe your classes in an easy to understand and maintain manner, embrace ES7 with strong fallbacks on ES5 compliant approaches.
• Fall into Success with Iridium's carefully designed API - which is structured to help ensure your code remains maintainable regardless of how large your project becomes.
• Amazing Documentation which covers the full Iridium API, and is always up to date thanks to the brilliant TypeDoc project, can be found at sierrasoftworks.github.io/Iridium.

Requirements

Iridium is built on top of a number of very modern technologies, including TypeScript 2.0, JavaScript ES6 and the latest MongoDB Node.js Driver (version 2.2). You'll need to be running Node.js 6.x, or 4.x with the --harmony flag to run version 7 of Iridium. For older versions of Node.js, please considering using version 6 of Iridium instead.

For starters, you will need to be running MongoDB 2.6 or later in order to use Iridium - however we recommend you use MongoDB 3.1 due to the various performance improvements they've made. If you're working with TypeScript, you will also need to use the 2.0 compiler or risk having the Iridium type definitions break your project.

Using Iridium

Rather than opt of the usual "Look how quickly you can do something" approach, we thought it might be useful to see an example which covers most of the stuff you'd need to do in Iridium. This example covers defining your own document interfaces, a custom schema and instance type which provides some additional methods.

You'll notice that the House class extends Iridium's Instance class, which gives it methods like save() as well as change tracking when calling save() on the instance. If you'd prefer a lighter approach or to use your own home-grown implementation then you can do so by taking a look at the Custom Instances section.

import {Core, Model, Instance, Collection, Index, Property, ObjectID} from 'iridium';

interface Colour {
    r: number;
    g: number;
    b: number;
}

interface Car {
    make: string;
    model: string;
    colour: Colour;
}

interface HouseDocument {
    _id?: string;
    name: string;

    cars?: Car[];
}

@Index({ name: 1 })
@Collection('houses')
class House extends Instance<HouseDocument, House> implements HouseDocument {
    @ObjectID _id: string;
    @Property(/^.+$/)
    name: string;

    @Property([{
        make: String,
        model: String,
        colour: {
            r: Number,
            g: Number,
            b: Number
        }
    }])
    cars: Car[];

    static onCreating(doc: HouseDocument) {
        doc.cars = doc.cars || [];
    }

    addCar(make: string, model: string, colour: Colour) {
        this.cars.push({
            make: make,
            model: model,
            colour: colour
        });
    }

    get numberOfCars() {
        return this.cars.length;
    }
}

class MyDatabase extends Core {
    Houses = new Model<HouseDocument, House>(this, House);
}

var myDb = new MyDatabase({ database: 'houses_test' });

myDb.connect().then(() => myDb.Houses.insert({
        name: 'My House',
        cars: [{
            make: 'Audi',
            model: 'A4',
            colour: { r: 0, g: 0, b: 0 }
        }]
    }))
    .then(() => myDb.Houses.get())
    .then((house) => {
        house.addCar('Audi', 'S4', { r: 255, g: 255, b: 255 });
        return house.save();
    })
    .then(() => myDb.close());

Defining a Model

Iridium models are created with a reference to their Core (which provides the database connection) and an InstanceType which is composed of a constructor function as well as a number of static properties providing configuration information for the instance.

JavaScript

new Model(core, InstanceType);

TypeScript

new Model<DocumentInterface, InstanceType>(core, InstanceType);

If you're working with TypeScript, you can provide an interface for the document structure used by the database, which will allow you to get useful type hints when you are creating documents. You can also provide the InstanceType to provide useful type information for any instances which are retrieved from the database. This information is carried through all promises and callbacks you will use within Iridium and it makes your life significantly easier.

Typically you will expose your models as variables on a custom Core implementation like this.

class MyCore extends Core {
    MyModel = new Model<MyDocumentInterface, MyInstanceType>(this, MyInstanceType);
}

The InstanceType Constructor

The InstanceType constructor is responsible for creating objects which represent a document retrieved from the database. It also provides a number of configuration details which are used to determine how Iridium works with the model.

There are two approaches to defining an instance constructor - the first is to create a true wrapper like the one provided by Iridium.Instance which offers helper methods like save() and remove(), which comes in very handy for writing concise descriptive code, while the other approach is to simply return the document received from the database - great for performance or security purposes.

TypeScript

interface Document {
    _id?: string;
}

class InstanceType {
    constructor(model: Model<Document, Instance>, document: Document, isNew: boolean = true, isPartial: boolean = false) {

    }

    _id: string;

    static schema: Iridium.Schema = {
        _id: false
    };

    static collection = 'myCollection';
}

JavaScript

module.exports = function(model, document, isNew, isPartial) {

}

module.exports.collection = 'myCollection';
module.exports.schema = {
    _id: false
};

Configuration Options

As we mentioned, configuration of a model is conducted through static properties on its constructor. These configuration options include the schema which is used to validate that all data inserted into the database through Iridium meets certain conditions, the collection which specifies the name of the MongoDB collection into which the documents are stashed and a couple of others worth noting.

Schema

Iridium uses Skmatc for schema validation, you can read more about it on its project page but we'll give a quick rundown of the way you make use of it here.

The model's schema is defined using an object in which keys represent their document property counterparts while the values represent a validation rule. You can also make use of the @Property decorator to automatically build up your schema object.

TypeScript

class InstanceType {
    _id: string;
    email: string;

    static schema: Iridium.Schema = {
        _id: false,
        email: /^.+@.+$/
    };
}

class InstanceType extends Iridium.Instance<any, InstanceType> {
    @Iridium.ObjectID
    _id: string;
    
    @Iridium.Property(String)
    email: string;
}

JavaScript

function InstanceType() {}

InstanceType.schema = {
    _id: false,
    email: /^.+@.+$/
};

The Iridium Instance Class

Instead of implementing your own instance constructor every time, Iridium offers a powerful and tested instance base class which provides a number of useful helper metho