#MongoWrap Wraps native node mongoDB driver, to provide persistent authenticated connection and routines useful to the construction of RESTful interfaces. MongoWrap's primary goal is to provide a wrapper for the more generic calls & persisted connection, but not block any native "db" functionality (i.e., best of both worlds).

###MongoWrap API ######Basics

• Install
• Basic Usage
• Configuration
• connect()

######Generic Methods:

• findAll()
• findById()
• insert()
• updateById()
• removeById()

######Utility Methods:

• show()
• todayAsISODate()
• dateAsISODate(date)

###Install #####Install from npm registry

    
    npm install mongo-wrap --save    

#####Clone from github

    
    git clone https://github.com/gmilligan/mongowrap.git    

###Basic Usage #####Use mongoDb "db" directly (passed in from "connect" method)

  // for calls requiring additional functionality 
  // than generic wrapper interface provides
  dbWrap.connect(function(err, db){
    db.collection('name')
      .find({},{},{})
      .toArray(...
  });
  
  // run an "aggregate" off "db" collection  

  dbWrap.connect(function(err, db){
    if(err) return cb(err);
    db.collection('name')
      .aggregate({$group: {_id: '$field'}}, 
      function(err, results){
      if(err) return cb(err);
      cb(null, results);
    });
  });

#####or, use MongoWrap's convenience methods for generic REST type calls

  var opts = {
    collection: @collection,
    id: @id
  }
  dbWrap.findById(opts, function(err, result){
    if(err) return cb(err);
    if(result) cb(null, result);
  });
    

###Instantiate & Configure MongoWrap

// create wrapper by passing in connect configuration
// this is likely stored in a json file or environment variables  

var config = {  
  "username": "username",  
  "password": "password",  
  "database": "database",  
  "host"    : "localhost", 
  "port"    : "27017",     
}
var dbWrap = new MongoWrap(config)

// - or inline - 
 
var dbWrap = new MongoWrap({
    username: "username",  
    password: "password",  
    database: "database",  
    host    : "localhost", 
    port    : "27017",     
});

###Create Connection (Express example)

// instantiate MongoWrap
var dbWrap = require('./server/tools/mongowrap/mongo-wrap')(cfg.mongo)

// share instance of MongoWrap to modules requiring db interaction
reportProvider = require('./server/data-providers/report-provider')(dbWrap) 

// start server after db is connected
dbWrap.connect(function(err, db) {
  if(err) throw err;

  app.listen(cfg.express.port);
  console.log('Started Local Server, Port:' + cfg.express.port);
});

###Generic Query & Manipulation Methods ####findAll() Returns array of documents, using user defined "query" & "sort"

Syntax:

    var query = {
      collection: @collection,
      where: {},
      sort: {}
    }
    dbWrap.findAll(query, function(err, results){
      if(err) return cb(err);
      if(results){...}
    });

==== ####findById() Returns a single document, located using item "id"

Syntax:

    var opts = {
      collection: @collection,
      id: @id
    }
    dbWrap.findById(opts, function(err, result){
      if(err) return cb(err);
      if(result) cb(null, result);
    });

==== ####insert() Insert a new document

Syntax:

    var opts = {
      collection: collectionName,
      data: {}
    }
    dbWrap.insert(opts, function(err, result){
      if(err) return cb(err);
      if(result} cb(null, result);
    })

==== ####updateById() Update existing document, using item "id"

Syntax:

   var opts = {
     collection: collectionName,
     id: @id,
     data: {}
   }
   dbWrap.updateById(opts, function(err, code){
     if(err) return cb(err);
     if(code.success===true) {...};
   });

==== ####removeById() Delete existing document, using item "id"

Syntax:

    var opts = {
      collection: @collection,
      id: @id
    }
    dbWrap.removeById(opts, function(err, code){
      if(err) return cb(err);
      if(code.success===true){...};
    });

###Utility Methods
####show() Log out a colored tree view of any JavaScript object. Handy to check results. Basically logs a util.inspect(data, true, 10, true) on the object. It is handy.

Syntax:

   dbWrap.show(doc);

####todayAsISODate() Return today's date as in ISO format

Syntax:

   var ISODate = dbWrap.todayAsISODate();
   

####dateAsISODate() Return a date in ISO format, if no date is passed in, it return today's date in ISO format.

Syntax:

   var ISODate = dbWrap.todayAsISODate(data);
   

####Thoughts/TODO:

• As every db call requires a collection name in the options parameter, it seems more intuitive to pass the collection name as a first parameter, or at least allow this as an option.
• As I have decided to share this library, I think may be time to move to a revealing module pattern and hide the internal _connect method.