Meerkat

An extremely thin mongo native driver wrapper that eliminates a surprising amount of boilerplate

Getting Started

Install Meerkat:

npm install meerkat --save

Examples

Meerkat was written to improve the experience of accessing MongoDB within the context of an Express app written in CoffeeScript. As such, the examples will demonstrate its usage in this context. However, Meerkat is not limited to use within Express and its API should translate well to pure JavaScript.

Express Middleware

The Meerkat Express middleware enhances the Express request object with a reference to the current Meerkat Connection and an alias to the Connection's collection method.

Initialize Connection and Middleware:

express = require 'express'
meerkat = require 'meerkat'
app = express()
app.configure ->
  app.use express.static public_dir
  # ... 
  app.use meerkat.middleware(app.locals)
  # ... 
  app.use express.router
  # ... 
{ options, uri } = config.mongodb
    meerkat.connect app.locals, options, uri, ->
      app.listen process.env.PORT || 3000

Use Meerkat Within Express Middleware/Routes:

# access the meerkat connection within express middlware 
(req, res, next) ->
  req.meerkat.collection('users').find_one id: req.params.id, (user) ->
    # do something with the users 

Or Better Yet...

# access meerkat collections within express middlware 
(req, res, next) ->
  req.collection('users').find_one id: req.params.id, (user) ->
    # do something with the users 

Connect to Mongo Outside of Express

{ options, uri } = config.mongodb
meerkat.connect options, uri, (connection) ->
  #work with the connection 

Already have a native connection:

  connection = meerkat.wrapper native
  # work with the connection 

Meerkat Collections

Single Use:

connection.collection('users').find_one id: req.params.id, (user) ->
  # do something with the user 

Multi-Use:

connection.collection 'users', (Users) ->
  Users.find_one id: req.params.id, (user) ->
    Users.find(id: $in: user.friends).all (friends) ->
      # do something with the user's friends 

Meerkat exposes Collection methods equivalent to the Mongo Native Driver with a snake_case as apposed to camelCase syntax. It also avoids a considerable amount of boilerplate by allowing for the configuration of a default failure callback. In the context of Express Middleware and intelligent default failure behavior is setup for you. Meerkat API calls map directly to Mongo Native Driver calls witht he following translation rules of thumb.

#native 
connection.collection 'users', (err, Users) ->
  throw err if err?
  Users.findOne id: req.params.id, (err, user) ->
    throw err if err?
    Users.find(id: $in: user.friends).toArray (err, friends) ->
      throw err if err?
      # do something with the user's friends 
 
#meerkat with custom failure handler 
failure = (err) -> 
  console.log err
  throw err
connection.collection 'users', failure, (Users) ->
  Users.find_one id: req.params.id, failure, (user) ->
    Users.find(id: $in: user.friends).all failure, (friends) ->
      # do something with the user's friends 
 
#meerkat with default error handler (common case) 
connection.collection 'users', (Users) ->
  Users.find_one id: req.params.id, (user) ->
    Users.find(id: $in: user.friends).all (friends) ->
      # do something with the user's friends 

Access a Cursor

The find method of a Meerkat Collection returns a Cursor much like the mongodb native driver with some key enhancements.

# get a cursor over all active users 
cursor = connection.collection('users').find active: true

A Merkat Cursor supports the following usage patterns:

# get a count of the results 
cursor.count()

Or:

# access all of the cursor's results as an array 
cursor.all (users) ->
  # do something with the active users 

Or:

# iterate over each of the cursor's results one at a time 
cursor.each (user) ->
  # perform an operation on each user 

Or:

# sort the users by last name and then access a specific slice of the results 
cursor.sort('name.last').limit(10).skip(10).all (users) ->
  # do something with the users 

Or:

# sort the users by last and first and use the pagination helper to access the second page of results 
cursor.sort('name.last').paginate 2, 10, (users, pagination) ->
  ###
  pagination metadata:
  pagination.total --> the total number of results matching the query
  pagination.pages --> the total number of pages in the cursor given the current results returned per page
  pagination.per --> the maxiumum number of results per page
  pagination.page --> the page number of the current page counting from 1
  ###
  # do something with the users 

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality.

Release History

(Nothing yet)