node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »



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

Getting Started

Install Meerkat:

npm install meerkat --save


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
  # ... 
{ optionsuri } = config.mongodb
    meerkat.connect app.localsoptionsuri->
      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: ->
    # do something with the users 

Or Better Yet...

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

Connect to Mongo Outside of Express

{ optionsuri } = config.mongodb
meerkat.connect optionsuri(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: ->
  # do something with the user 


connection.collection 'users'(Users) ->
  Users.find_one id: ->
    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.

connection.collection 'users'(err, Users) ->
  throw err if err?
  Users.findOne id:, 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.idfailure(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: ->
    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 


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


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


# 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 


# sort the users by last and first and use the pagination helper to access the second page of results 
cursor.sort('name.last').paginate 210(users, pagination) ->
  pagination metadata: --> 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 --> the page number of the current page counting from 1
  # do something with the users 


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)