Mongorito

NPM Github Twitter

Easy-to-work-with MongoDB ODM for Node.js. Built-in caching with memcached. Clean codebase.

Features

Installation

npm install mongorito

Usage

Mongorito = require 'mongorito'

Mongorito.connect ['mongo://user:password@127.0.0.1:27017/databaseName']
Mongorito.cache ['127.0.0.1:11211'] # optional, allows automatic, smart caching. It is just one line to enable it!

class Post
    constructor: ->
        super 'posts' # telling our collection name

Post = Mongorito.bake Post # Now, we are ready to go!

post = new Post
post.title = 'Very interesting article.'
post.content = 'Really, really, exciting.'
post.save (err) ->
    # saved!

    post.title = 'Edited title!'
    post.save (err) ->
        # updated!

        post.remove ->
            # removed!

Post.find title : 'Some title!', (err, posts) ->
    for post in posts
        # post is an instance of Post model, so you can perform usual methods on it
        post.remove ->

Examples

You can find an up-to-date collection of examples in Mongorito's Github repository, in the examples folder.

Documentation

Connecting

This is how you can connect to one or many MongoDB databases:

Mongorito = require 'Mongorito'

Mongorito.connect ['mongo://user:password@127.0.0.1:27017/databaseName'] # array can contain uris to multiple servers

Defining

You can define model this way:

class Post
	constructor: ->
		super 'posts' # telling Mongorito name of the collection
	
Post = Mongorito.bake Post # it would not be interesting without dark magic, right?

Finding

Let's take a walk and see how can you find documents, sort, limit and skip some of them. First, let's just find some documents without additional requirements:

Post.find (err, posts) ->
	# posts is an array of all documents in the "posts" collection

Now, let's add some criteria:

Post.find title: 'I love Apple', (err, posts) ->
	# posts is an array of all documents, who have "I love Apple" title

What if we want to sort documents by their creation date?

Post.find sort: _id: -1, (err, posts) ->
	# posts is an array of all documents, sorted by _id

Of course, sometimes we have to limit our results and do some pagination:

Post.find limit: 5, skip: 2, (err, posts) ->
	# skipping first 2 documents, and getting only 5

Post.find title: 'I love Apple', limit: 5, skip: 2, (err, posts) ->
	# skipping first 2, getting only 5 documents who have title "I love Apple"

And sometimes we have to order and limit:

Post.find author: 'Steve', limit: 5, skip: 2, sort: _id: -1, (err, posts) ->
	# finding documents with author "Steve", sorting them by _id, skipping first 2 and limiting result to 5 records

Forgot to mention, that in all these examples, posts array contains Mongorito models, so you can do usual operations with them. Keep reading ;-)

Creating

Let's create some new documents in our posts collection:

post = new Post
post.title = 'I love Apple'
post.author = 'Steve'
post.body = 'Who does not like Apple?'
post.save ->
	# post saved

Notice, that you don't need to declare fields in the model, Mongorito automatically detects what belongs to you, and what is not.

Updating

Updating the document is as easy as creating it:

Post.find title: 'I love Apple', (err, posts) ->
	post = posts[0] # let's take the first one
	post.title = 'I love Apple more than Microsoft'
	post.save ->
		# post updated

Removing

Post.find title: 'I love Apple', (err, posts) ->
	posts[0].remove ->
		# post removed

Hooking

Mongorito provides you with such hooks as: beforeCreate, afterCreate, aroundCreate, beforeUpdate, afterUpdate, aroundUpdate. Let me know if you need more, I'll add them.

class Post
	constructor: ->
		super 'posts'
	
	beforeCreate: -> # before creating
	
	afterCreate: -> # after creating
	
	aroundCreate: -> # before and after creating(double execution)
	
	beforeUpdate: -> # before updating
	
	afterUpdate: -> # after updating
	
	aroundUpdate: -> # before and after updating

Post = Mongorito.bake Post

Validating

Mongorito supports only async validations, sorry.

class Tweet
	constructor: ->
		super 'tweets'

	validateBody: (callback) -> # you should pass false, if invalid and true, if valid
		if @body.length >= 140
			callback false
		else
			callback true

Tweet = Mongorito.bake Tweet

tweet = new Tweet
tweet.body = 'I want to be super-super-super-super long! Reallly, reallly, long!!!! In fact, I am VEEERY long! You\'ve never seen such a looooooong tweeeeeet!'
tweet.save (err, results) ->
	# results will be ['body'], because body field did not pass validation

Caching

Mongorito offers built-in caching via Memcacher, which adds tags functionality to memcached, without modifying it. To force Mongorito to cache documents automatically, you need to write just one line:

Mongorito.cache ['127.0.0.1:11211'] # array of memcached servers