mongodb 2.1.0-alpha → 2.1.2

package/lib/db.js

@@ -16,6 +16,7 @@ var EventEmitter = require('events').EventEmitter
   , CoreReadPreference = require('mongodb-core').ReadPreference
   , MongoError = require('mongodb-core').MongoError
   , ObjectID = require('mongodb-core').ObjectID
+  , Define = require('./metadata')
   , Logger = require('mongodb-core').Logger
   , Collection = require('./collection')
   , crypto = require('crypto');
@@ -53,14 +54,15 @@ var debugFields = ['authSource', 'w', 'wtimeout', 'j', 'native_parser', 'forceSe
  * @param {boolean} [options.native_parser=true] Select C++ bson parser instead of JavaScript parser.
  * @param {boolean} [options.forceServerObjectId=false] Force server to assign _id values instead of driver.
  * @param {boolean} [options.serializeFunctions=false] Serialize functions on any object.
+ * @param {Boolean} [options.ignoreUndefined=false] Specify if the BSON serializer should ignore undefined fields.
  * @param {boolean} [options.raw=false] Return document results as raw BSON buffers.
  * @param {boolean} [options.promoteLongs=true] Promotes Long values to number if they fit inside the 53 bits resolution.
  * @param {number} [options.bufferMaxEntries=-1] Sets a cap on how many operations the driver will buffer up before giving up on getting a working connection, default is -1 which is unlimited.
- * @param {number} [options.numberOfRetries=5] Number of retries off connection.
- * @param {number} [options.retryMiliSeconds=500] Number of milliseconds between retries.
  * @param {(ReadPreference|string)} [options.readPreference=null] The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST).
  * @param {object} [options.pkFactory=null] A primary key factory object for generation of custom _id keys.
  * @param {object} [options.promiseLibrary=null] A Promise library class the application wishes to use such as Bluebird, must be ES6 compatible
+ * @param {object} [options.readConcern=null] Specify a read concern for the collection. (only MongoDB 3.2 or higher supported)
+ * @param {object} [options.readConcern.level='local'] Specify a read concern level for the collection operations, one of [local|majority]. (only MongoDB 3.2 or higher supported)
  * @property {(Server|ReplSet|Mongos)} serverConfig Get the current db topology.
  * @property {number} bufferMaxEntries Current bufferMaxEntries value for the database
  * @property {string} databaseName The name of the database this instance represents.
@@ -99,6 +101,8 @@ var Db = function(databaseName, topology, options) {
   this.s = {
     // Database name
       databaseName: databaseName
+    // DbCache
+    , dbCache: {}
     // Children db's
     , children: []
     // Topology
@@ -123,6 +127,10 @@ var Db = function(databaseName, topology, options) {
     , nativeParser: options.nativeParser || options.native_parser
     // Promise library
     , promiseLibrary: promiseLibrary
+    // No listener
+    , noListener: typeof options.noListener == 'boolean' ? options.noListener : false
+    // ReadConcern
+    , readConcern: options.readConcern
   }
 
   // Ensure we have a valid db name
@@ -180,12 +188,13 @@ var Db = function(databaseName, topology, options) {
 
   // This is a child db, do not register any listeners
   if(options.parentDb) return;
+  if(this.s.noListener) return;
 
   // Add listeners
-  topology.once('error', createListener(self, 'error', self));
-  topology.once('timeout', createListener(self, 'timeout', self));
+  topology.on('error', createListener(self, 'error', self));
+  topology.on('timeout', createListener(self, 'timeout', self));
   topology.on('close', createListener(self, 'close', self));
-  topology.once('parseError', createListener(self, 'parseError', self));
+  topology.on('parseError', createListener(self, 'parseError', self));
   topology.once('open', createListener(self, 'open', self));
   topology.once('fullsetup', createListener(self, 'fullsetup', self));
   topology.once('all', createListener(self, 'all', self));
@@ -194,6 +203,8 @@ var Db = function(databaseName, topology, options) {
 
 inherits(Db, EventEmitter);
 
+var define = Db.define = new Define('Db', Db, false);
+
 /**
  * The callback format for the Db.open method
  * @callback Db~openCallback
@@ -214,13 +225,13 @@ var open = function(self, callback) {
     }
 
     internalCallback(null, self);
-  });    
+  });
 }
 
 /**
  * Open the database
  * @method
- * @param {Db~openCallback} callback Callback
+ * @param {Db~openCallback} [callback] Callback
  * @return {Promise} returns Promise if no callback passed
  */
 Db.prototype.open = function(callback) {
@@ -236,6 +247,8 @@ Db.prototype.open = function(callback) {
   });
 }
 
+define.classMethod('open', {callback: true, promise:true});
+
 /**
  * The callback format for results
  * @callback Db~resultCallback
@@ -244,6 +257,9 @@ Db.prototype.open = function(callback) {
  */
 
 var executeCommand = function(self, command, options, callback) {
+  // Did the user destroy the topology
+  if(self.serverConfig && self.serverConfig.isDestroyed()) return callback(new MongoError('topology was destroyed'));
+  // Get the db name we are executing against
   var dbName = options.dbName || options.authdb || self.s.databaseName;
   // If we have a readPreference set
   if(options.readPreference == null && self.s.readPreference) {
@@ -265,6 +281,7 @@ var executeCommand = function(self, command, options, callback) {
   // Execute command
   self.s.topology.command(f('%s.$cmd', dbName), command, options, function(err, result) {
     if(err) return handleCallback(callback, err);
+    if(options.full) return handleCallback(callback, null, result);
     handleCallback(callback, null, result.result);
   });
 }
@@ -275,8 +292,7 @@ var executeCommand = function(self, command, options, callback) {
  * @param {object} command The command hash
  * @param {object} [options=null] Optional settings.
  * @param {(ReadPreference|string)} [options.readPreference=null] The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST).
- * @param {number} [options.maxTimeMS=null] Number of milliseconds to wait before aborting the query.
- * @param {Db~resultCallback} callback The command result callback
+ * @param {Db~resultCallback} [callback] The command result callback
  * @return {Promise} returns Promise if no callback passed
  */
 Db.prototype.command = function(command, options, callback) {
@@ -285,7 +301,7 @@ Db.prototype.command = function(command, options, callback) {
   if(typeof options == 'function') callback = options, options = {};
   // Clone the options
   options = shallowClone(options);
-  
+
   // Do we have a callback
   if(typeof callback == 'function') return executeCommand(self, command, options, callback);
   // Return a promise
@@ -297,6 +313,8 @@ Db.prototype.command = function(command, options, callback) {
   });
 }
 
+define.classMethod('command', {callback: true, promise:true});
+
 /**
  * The callback format for results
  * @callback Db~noResultCallback
@@ -308,7 +326,7 @@ Db.prototype.command = function(command, options, callback) {
  * Close the db and it's underlying connections
  * @method
  * @param {boolean} force Force close, emitting no events
- * @param {Db~noResultCallback} callback The result callback
+ * @param {Db~noResultCallback} [callback] The result callback
  * @return {Promise} returns Promise if no callback passed
  */
 Db.prototype.close = function(force, callback) {
@@ -325,13 +343,13 @@ Db.prototype.close = function(force, callback) {
       // Fire close on all children
       for(var i = 0; i < this.s.children.length; i++) {
         this.s.children[i].emit('close');
-      }      
+      }
     }
 
     // Remove listeners after emit
-    self.removeAllListeners('close');    
+    self.removeAllListeners('close');
   }
-  
+
   // Close parent db if set
   if(this.s.parentDb) this.s.parentDb.close();
   // Callback after next event loop tick
@@ -345,6 +363,8 @@ Db.prototype.close = function(force, callback) {
   });
 }
 
+define.classMethod('close', {callback: true, promise:true});
+
 /**
  * Return the Admin db instance
  * @method
@@ -354,6 +374,8 @@ Db.prototype.admin = function() {
   return new Admin(this, this.s.topology, this.s.promiseLibrary);
 };
 
+define.classMethod('admin', {callback: false, promise:false, returns: [Admin]});
+
 /**
  * The callback format for the collection method, must be used if strict is specified
  * @callback Db~collectionResultCallback
@@ -376,6 +398,8 @@ Db.prototype.admin = function() {
  * @param {(ReadPreference|string)} [options.readPreference=null] The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST).
  * @param {boolean} [options.serializeFunctions=false] Serialize functions on any object.
  * @param {boolean} [options.strict=false] Returns an error if the collection does not exist
+ * @param {object} [options.readConcern=null] Specify a read concern for the collection. (only MongoDB 3.2 or higher supported)
+ * @param {object} [options.readConcern.level='local'] Specify a read concern level for the collection operations, one of [local|majority]. (only MongoDB 3.2 or higher supported)
  * @param {Db~collectionResultCallback} callback The collection result callback
  * @return {Collection} return the new Collection instance if not in strict mode
  */
@@ -387,6 +411,14 @@ Db.prototype.collection = function(name, options, callback) {
   // Set the promise library
   options.promiseLibrary = this.s.promiseLibrary;
 
+  // If we have not set a collection level readConcern set the db level one
+  options.readConcern = options.readConcern || this.s.readConcern;
+
+  // Do we have ignoreUndefined set
+  if(this.s.options.ignoreUndefined) {
+    options.ignoreUndefined = this.s.options.ignoreUndefined;
+  }
+
   // Execute
   if(options == null || !options.strict) {
     try {
@@ -417,15 +449,19 @@ Db.prototype.collection = function(name, options, callback) {
   });
 }
 
+define.classMethod('collection', {callback: true, promise:false, returns: [Collection]});
+
 var createCollection = function(self, name, options, callback) {
   // Get the write concern options
   var finalOptions = writeConcern(shallowClone(options), self, options);
+  // Did the user destroy the topology
+  if(self.serverConfig && self.serverConfig.isDestroyed()) return callback(new MongoError('topology was destroyed'));
 
   // Check if we have the name
   self.listCollections({name: name}).toArray(function(err, collections) {
     if(err != null) return handleCallback(callback, err, null);
     if(collections.length > 0 && finalOptions.strict) {
-      return handleCallback(callback, new MongoError(f("Collection %s already exists. Currently in strict mode.", name)), null);
+      return handleCallback(callback, MongoError.create({message: f("Collection %s already exists. Currently in strict mode.", name), driver:true}), null);
     } else if (collections.length > 0) {
       try { return handleCallback(callback, null, new Collection(self, self.s.topology, self.s.databaseName, name, self.s.pkFactory, options)); }
       catch(err) { return handleCallback(callback, err); }
@@ -445,7 +481,7 @@ var createCollection = function(self, name, options, callback) {
       if(err) return handleCallback(callback, err);
       handleCallback(callback, null, new Collection(self, self.s.topology, self.s.databaseName, name, self.s.pkFactory, options));
     });
-  });  
+  });
 }
 
 /**
@@ -466,7 +502,7 @@ var createCollection = function(self, name, options, callback) {
  * @param {number} [options.size=null] The size of the capped collection in bytes.
  * @param {number} [options.max=null] The maximum number of documents in the capped collection.
  * @param {boolean} [options.autoIndexId=true] Create an index on the _id field of the document, True by default on MongoDB 2.2 or higher off for version < 2.2.
- * @param {Db~collectionResultCallback} callback The results callback
+ * @param {Db~collectionResultCallback} [callback] The results callback
  * @return {Promise} returns Promise if no callback passed
  */
 Db.prototype.createCollection = function(name, options, callback) {
@@ -477,6 +513,9 @@ Db.prototype.createCollection = function(name, options, callback) {
   name = args.length ? args.shift() : null;
   options = args.length ? args.shift() || {} : {};
 
+  // Do we have a promisesLibrary
+  options.promiseLibrary = options.promiseLibrary || this.s.promiseLibrary;
+
   // Check if the callback is in fact a string
   if(typeof callback == 'string') name = callback;
 
@@ -490,13 +529,15 @@ Db.prototype.createCollection = function(name, options, callback) {
   });
 }
 
+define.classMethod('createCollection', {callback: true, promise:true});
+
 /**
  * Get all the db statistics.
  *
  * @method
  * @param {object} [options=null] Optional settings.
  * @param {number} [options.scale=null] Divide the returned sizes by scale value.
- * @param {Db~resultCallback} callback The collection result callback
+ * @param {Db~resultCallback} [callback] The collection result callback
  * @return {Promise} returns Promise if no callback passed
  */
 Db.prototype.stats = function(options, callback) {
@@ -510,6 +551,8 @@ Db.prototype.stats = function(options, callback) {
   return this.command(commandObject, options, callback);
 }
 
+define.classMethod('stats', {callback: true, promise:true});
+
 // Transformation methods for cursor results
 var listCollectionsTranforms = function(databaseName) {
   var matching = f('%s.', databaseName);
@@ -534,6 +577,7 @@ var listCollectionsTranforms = function(databaseName) {
  * @param {object} filter Query to filter collections by
  * @param {object} [options=null] Optional settings.
  * @param {number} [options.batchSize=null] The batchSize for the returned command cursor or if pre 2.8 the systems batch collection
+ * @param {(ReadPreference|string)} [options.readPreference=null] The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST).
  * @return {CommandCursor}
  */
 Db.prototype.listCollections = function(filter, options) {
@@ -544,7 +588,6 @@ Db.prototype.listCollections = function(filter, options) {
   options = shallowClone(options);
   // Set the promise library
   options.promiseLibrary = this.s.promiseLibrary;
-
   // We have a list collections command
   if(this.serverConfig.capabilities().hasListCollectionsCommand) {
     // Cursor options
@@ -555,8 +598,12 @@ Db.prototype.listCollections = function(filter, options) {
     options.cursorFactory = CommandCursor;
     // Filter out the correct field values
     options.transforms = listCollectionsTranforms(this.s.databaseName);
-    // Execute the cursor
-    return this.s.topology.cursor(f('%s.$cmd', this.s.databaseName), command, options);
+    // Create the cursor
+    var cursor = this.s.topology.cursor(f('%s.$cmd', this.s.databaseName), command, options);
+    // Do we have a readPreference, apply it
+    if(options.readPeference) cursor.setReadPreference(options.readPeference);
+    // Return the cursor
+    return cursor;
   }
 
   // We cannot use the listCollectionsCommand
@@ -581,19 +628,26 @@ Db.prototype.listCollections = function(filter, options) {
   }
 
   // Return options
-  var options = {transforms: listCollectionsTranforms(this.s.databaseName)}
+  var _options = {transforms: listCollectionsTranforms(this.s.databaseName)}
   // Get the cursor
-  var cursor = this.collection(Db.SYSTEM_NAMESPACE_COLLECTION).find(filter, options);
+  var cursor = this.collection(Db.SYSTEM_NAMESPACE_COLLECTION).find(filter, _options);
+  // Do we have a readPreference, apply it
+  if(options.readPeference) cursor.setReadPreference(options.readPeference);
   // Set the passed in batch size if one was provided
   if(options.batchSize) cursor = cursor.batchSize(options.batchSize);
   // We have a fallback mode using legacy systems collections
   return cursor;
 };
 
+define.classMethod('listCollections', {callback: false, promise:false, returns: [CommandCursor]});
+
 var evaluate = function(self, code, parameters, options, callback) {
   var finalCode = code;
   var finalParameters = [];
 
+  // Did the user destroy the topology
+  if(self.serverConfig && self.serverConfig.isDestroyed()) return callback(new MongoError('topology was destroyed'));
+
   // If not a code object translate to one
   if(!(finalCode instanceof Code)) finalCode = new Code(finalCode);
   // Ensure the parameters are correct
@@ -617,9 +671,9 @@ var evaluate = function(self, code, parameters, options, callback) {
   self.command(cmd, options, function(err, result) {
     if(err) return handleCallback(callback, err, null);
     if(result && result.ok == 1) return handleCallback(callback, null, result.retval);
-    if(result) return handleCallback(callback, new MongoError(f("eval failed: %s", result.errmsg)), null);
+    if(result) return handleCallback(callback, MongoError.create({message: f("eval failed: %s", result.errmsg), driver:true}), null);
     handleCallback(callback, err, result);
-  });  
+  });
 }
 
 /**
@@ -630,7 +684,8 @@ var evaluate = function(self, code, parameters, options, callback) {
  * @param {(object|array)} parameters The parameters for the call.
  * @param {object} [options=null] Optional settings.
  * @param {boolean} [options.nolock=false] Tell MongoDB not to block on the evaulation of the javascript.
- * @param {Db~resultCallback} callback The results callback
+ * @param {Db~resultCallback} [callback] The results callback
+ * @deprecated Eval is deprecated on MongoDB 3.2 and forward
  * @return {Promise} returns Promise if no callback passed
  */
 Db.prototype.eval = function(code, parameters, options, callback) {
@@ -652,6 +707,8 @@ Db.prototype.eval = function(code, parameters, options, callback) {
   });
 };
 
+define.classMethod('eval', {callback: true, promise:true});
+
 /**
  * Rename a collection.
  *
@@ -660,7 +717,7 @@ Db.prototype.eval = function(code, parameters, options, callback) {
  * @param {string} toCollection New name of of the collection.
  * @param {object} [options=null] Optional settings.
  * @param {boolean} [options.dropTarget=false] Drop the target name collection if it previously exists.
- * @param {Db~collectionResultCallback} callback The results callback
+ * @param {Db~collectionResultCallback} [callback] The results callback
  * @return {Promise} returns Promise if no callback passed
  */
 Db.prototype.renameCollection = function(fromCollection, toCollection, options, callback) {
@@ -673,7 +730,7 @@ Db.prototype.renameCollection = function(fromCollection, toCollection, options,
   // Check if the callback is in fact a string
   if(typeof callback == 'function') {
     return this.collection(fromCollection).rename(toCollection, options, callback);
-  } 
+  }
 
   // Return a promise
   return new this.s.promiseLibrary(function(resolve, reject) {
@@ -684,12 +741,14 @@ Db.prototype.renameCollection = function(fromCollection, toCollection, options,
   });
 };
 
+define.classMethod('renameCollection', {callback: true, promise:true});
+
 /**
  * Drop a collection from the database, removing it permanently. New accesses will create a new collection.
  *
  * @method
  * @param {string} name Name of collection to drop
- * @param {Db~resultCallback} callback The results callback
+ * @param {Db~resultCallback} [callback] The results callback
  * @return {Promise} returns Promise if no callback passed
  */
 Db.prototype.dropCollection = function(name, callback) {
@@ -700,6 +759,8 @@ Db.prototype.dropCollection = function(name, callback) {
 
   // Check if the callback is in fact a string
   if(typeof callback == 'function') return this.command(cmd, this.s.options, function(err, result) {
+    // Did the user destroy the topology
+    if(self.serverConfig && self.serverConfig.isDestroyed()) return callback(new MongoError('topology was destroyed'));
     if(err) return handleCallback(callback, err);
     if(result.ok) return handleCallback(callback, null, true);
     handleCallback(callback, null, false);
@@ -709,13 +770,17 @@ Db.prototype.dropCollection = function(name, callback) {
   return new this.s.promiseLibrary(function(resolve, reject) {
     // Execute command
     self.command(cmd, self.s.options, function(err, result) {
-      if(err) return reject(err);      
+      // Did the user destroy the topology
+      if(self.serverConfig && self.serverConfig.isDestroyed()) return reject(new MongoError('topology was destroyed'));
+      if(err) return reject(err);
       if(result.ok) return resolve(true);
       resolve(false);
     });
   });
 };
 
+define.classMethod('dropCollection', {callback: true, promise:true});
+
 /**
  * Drop a database.
  *
@@ -725,12 +790,13 @@ Db.prototype.dropCollection = function(name, callback) {
  */
 Db.prototype.dropDatabase = function(callback) {
   var self = this;
-  if(typeof options == 'function') callback = options, options = {};
   // Drop database command
   var cmd = {'dropDatabase':1};
 
   // Check if the callback is in fact a string
   if(typeof callback == 'function') return this.command(cmd, this.s.options, function(err, result) {
+    // Did the user destroy the topology
+    if(self.serverConfig && self.serverConfig.isDestroyed()) return callback(new MongoError('topology was destroyed'));
     if(callback == null) return;
     if(err) return handleCallback(callback, err, null);
     handleCallback(callback, null, result.ok ? true : false);
@@ -740,20 +806,23 @@ Db.prototype.dropDatabase = function(callback) {
   return new this.s.promiseLibrary(function(resolve, reject) {
     // Execute command
     self.command(cmd, self.s.options, function(err, result) {
-      if(err) return reject(err);      
+      // Did the user destroy the topology
+      if(self.serverConfig && self.serverConfig.isDestroyed()) return reject(new MongoError('topology was destroyed'));
+      if(err) return reject(err);
       if(result.ok) return resolve(true);
       resolve(false);
     });
   });
 }
 
+define.classMethod('dropDatabase', {callback: true, promise:true});
+
 /**
  * The callback format for the collections method.
  * @callback Db~collectionsResultCallback
  * @param {MongoError} error An error instance representing the error during the execution.
  * @param {Collection[]} collections An array of all the collections objects for the db instance.
  */
-
 var collections = function(self, callback) {
   // Let's get the collection names
   self.listCollections().toArray(function(err, documents) {
@@ -767,7 +836,7 @@ var collections = function(self, callback) {
     handleCallback(callback, null, documents.map(function(d) {
       return new Collection(self, self.s.topology, self.s.databaseName, d.name.replace(self.s.databaseName + ".", ''), self.s.pkFactory, self.s.options);
     }));
-  });  
+  });
 }
 
 /**
@@ -791,6 +860,8 @@ Db.prototype.collections = function(callback) {
   });
 };
 
+define.classMethod('collections', {callback: true, promise:true});
+
 /**
  * Runs a command on the database as admin.
  * @method
@@ -798,7 +869,7 @@ Db.prototype.collections = function(callback) {
  * @param {object} [options=null] Optional settings.
  * @param {(ReadPreference|string)} [options.readPreference=null] The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST).
  * @param {number} [options.maxTimeMS=null] Number of milliseconds to wait before aborting the query.
- * @param {Db~resultCallback} callback The command result callback
+ * @param {Db~resultCallback} [callback] The command result callback
  * @return {Promise} returns Promise if no callback passed
  */
 Db.prototype.executeDbAdminCommand = function(selector, options, callback) {
@@ -812,6 +883,8 @@ Db.prototype.executeDbAdminCommand = function(selector, options, callback) {
 
   // Return the callback
   if(typeof callback == 'function') return self.s.topology.command('admin.$cmd', selector, options, function(err, result) {
+    // Did the user destroy the topology
+    if(self.serverConfig && self.serverConfig.isDestroyed()) return callback(new MongoError('topology was destroyed'));
     if(err) return handleCallback(callback, err);
     handleCallback(callback, null, result.result);
   });
@@ -819,37 +892,15 @@ Db.prototype.executeDbAdminCommand = function(selector, options, callback) {
   // Return promise
   return new self.s.promiseLibrary(function(resolve, reject) {
     self.s.topology.command('admin.$cmd', selector, options, function(err, result) {
+      // Did the user destroy the topology
+      if(self.serverConfig && self.serverConfig.isDestroyed()) return reject(new MongoError('topology was destroyed'));
       if(err) return reject(err);
       resolve(result.result);
     });
   });
 };
 
-var createIndex = function(self, name, fieldOrSpec, options, callback) {
-  // Get the write concern options
-  var finalOptions = writeConcern({}, self, options);
-  // Ensure we have a callback
-  if(finalOptions.writeConcern && typeof callback != 'function') {
-    throw new MongoError("Cannot use a writeConcern without a provided callback");
-  }
-
-  // Attempt to run using createIndexes command
-  createIndexUsingCreateIndexes(self, name, fieldOrSpec, options, function(err, result) {
-    if(err == null) return handleCallback(callback, err, result);
-    // Create command
-    var doc = createCreateIndexCommand(self, name, fieldOrSpec, options);
-    // Set no key checking
-    finalOptions.checkKeys = false;
-    // Insert document
-    self.s.topology.insert(f("%s.%s", self.s.databaseName, Db.SYSTEM_INDEX_COLLECTION), doc, finalOptions, function(err, result) {
-      if(callback == null) return;
-      if(err) return handleCallback(callback, err);
-      if(result == null) return handleCallback(callback, null, null);
-      if(result.result.writeErrors) return handleCallback(callback, MongoError.create(result.result.writeErrors[0]), null);
-      handleCallback(callback, null, doc.name);
-    });
-  });
-}
+define.classMethod('executeDbAdminCommand', {callback: true, promise:true});
 
 /**
  * Creates an index on the db and collection collection.
@@ -869,7 +920,7 @@ var createIndex = function(self, name, fieldOrSpec, options, callback) {
  * @param {number} [options.v=null] Specify the format version of the indexes.
  * @param {number} [options.expireAfterSeconds=null] Allows you to expire data on indexes applied to a data (MongoDB 2.2 or higher)
  * @param {number} [options.name=null] Override the autogenerated index name (useful if the resulting name is larger than 128 bytes)
- * @param {Db~resultCallback} callback The command result callback
+ * @param {Db~resultCallback} [callback] The command result callback
  * @return {Promise} returns Promise if no callback passed
  */
 Db.prototype.createIndex = function(name, fieldOrSpec, options, callback) {
@@ -896,27 +947,37 @@ Db.prototype.createIndex = function(name, fieldOrSpec, options, callback) {
   });
 };
 
-var ensureIndex = function(self, name, fieldOrSpec, options, callback) {
+var createIndex = function(self, name, fieldOrSpec, options, callback) {
   // Get the write concern options
   var finalOptions = writeConcern({}, self, options);
-  // Create command
-  var selector = createCreateIndexCommand(self, name, fieldOrSpec, options);
-  var index_name = selector.name;
+  // Ensure we have a callback
+  if(finalOptions.writeConcern && typeof callback != 'function') {
+    throw MongoError.create({message: "Cannot use a writeConcern without a provided callback", driver:true});
+  }
 
-  // Default command options
-  var commandOptions = {};
-  // Check if the index allready exists
-  self.indexInformation(name, finalOptions, function(err, indexInformation) {
-    if(err != null && err.code != 26) return handleCallback(callback, err, null);
-    // If the index does not exist, create it
-    if(indexInformation == null || !indexInformation[index_name])  {
-      self.createIndex(name, fieldOrSpec, options, callback);
-    } else {
-      if(typeof callback === 'function') return handleCallback(callback, null, index_name);
-    }
-  });  
+  // Did the user destroy the topology
+  if(self.serverConfig && self.serverConfig.isDestroyed()) return callback(new MongoError('topology was destroyed'));
+
+  // Attempt to run using createIndexes command
+  createIndexUsingCreateIndexes(self, name, fieldOrSpec, options, function(err, result) {
+    if(err == null) return handleCallback(callback, err, result);
+    // Create command
+    var doc = createCreateIndexCommand(self, name, fieldOrSpec, options);
+    // Set no key checking
+    finalOptions.checkKeys = false;
+    // Insert document
+    self.s.topology.insert(f("%s.%s", self.s.databaseName, Db.SYSTEM_INDEX_COLLECTION), doc, finalOptions, function(err, result) {
+      if(callback == null) return;
+      if(err) return handleCallback(callback, err);
+      if(result == null) return handleCallback(callback, null, null);
+      if(result.result.writeErrors) return handleCallback(callback, MongoError.create(result.result.writeErrors[0]), null);
+      handleCallback(callback, null, doc.name);
+    });
+  });
 }
 
+define.classMethod('createIndex', {callback: true, promise:true});
+
 /**
  * Ensures that an index exists, if it does not it creates it
  * @method
@@ -936,7 +997,7 @@ var ensureIndex = function(self, name, fieldOrSpec, options, callback) {
  * @param {number} [options.v=null] Specify the format version of the indexes.
  * @param {number} [options.expireAfterSeconds=null] Allows you to expire data on indexes applied to a data (MongoDB 2.2 or higher)
  * @param {number} [options.name=null] Override the autogenerated index name (useful if the resulting name is larger than 128 bytes)
- * @param {Db~resultCallback} callback The command result callback
+ * @param {Db~resultCallback} [callback] The command result callback
  * @return {Promise} returns Promise if no callback passed
  */
 Db.prototype.ensureIndex = function(name, fieldOrSpec, options, callback) {
@@ -946,7 +1007,7 @@ Db.prototype.ensureIndex = function(name, fieldOrSpec, options, callback) {
 
   // If we have a callback fallback
   if(typeof callback == 'function') return ensureIndex(self, name, fieldOrSpec, options, callback);
-  
+
   // Return a promise
   return new this.s.promiseLibrary(function(resolve, reject) {
     ensureIndex(self, name, fieldOrSpec, options, function(err, r) {
@@ -956,38 +1017,86 @@ Db.prototype.ensureIndex = function(name, fieldOrSpec, options, callback) {
   });
 };
 
+var ensureIndex = function(self, name, fieldOrSpec, options, callback) {
+  // Get the write concern options
+  var finalOptions = writeConcern({}, self, options);
+  // Create command
+  var selector = createCreateIndexCommand(self, name, fieldOrSpec, options);
+  var index_name = selector.name;
+
+  // Did the user destroy the topology
+  if(self.serverConfig && self.serverConfig.isDestroyed()) return callback(new MongoError('topology was destroyed'));
+
+  // Default command options
+  var commandOptions = {};
+  // Check if the index allready exists
+  self.indexInformation(name, finalOptions, function(err, indexInformation) {
+    if(err != null && err.code != 26) return handleCallback(callback, err, null);
+    // If the index does not exist, create it
+    if(indexInformation == null || !indexInformation[index_name])  {
+      self.createIndex(name, fieldOrSpec, options, callback);
+    } else {
+      if(typeof callback === 'function') return handleCallback(callback, null, index_name);
+    }
+  });
+}
+
+define.classMethod('ensureIndex', {callback: true, promise:true});
+
 Db.prototype.addChild = function(db) {
   if(this.s.parentDb) return this.s.parentDb.addChild(db);
   this.s.children.push(db);
 }
 
 /**
- * Create a new Db instance sharing the current socket connections.
+ * Create a new Db instance sharing the current socket connections. Be aware that the new db instances are
+ * related in a parent-child relationship to the original instance so that events are correctly emitted on child
+ * db instances. Child db instances are cached so performing db('db1') twice will return the same instance.
+ * You can control these behaviors with the options noListener and returnNonCachedInstance.
+ *
  * @method
  * @param {string} name The name of the database we want to use.
+ * @param {object} [options=null] Optional settings.
+ * @param {boolean} [options.noListener=false] Do not make the db an event listener to the original connection.
+ * @param {boolean} [options.returnNonCachedInstance=false] Control if you want to return a cached instance or have a new one created
  * @return {Db}
  */
-Db.prototype.db = function(dbName) {
+Db.prototype.db = function(dbName, options) {
+  options = options || {};
   // Copy the options and add out internal override of the not shared flag
-  var options = {};
   for(var key in this.options) {
     options[key] = this.options[key];
   }
 
+  // Do we have the db in the cache already
+  if(this.s.dbCache[dbName] && options.returnNonCachedInstance !== true) {
+    return this.s.dbCache[dbName];
+  }
+
   // Add current db as parentDb
-  options.parentDb = this;
+  if(options.noListener == null || options.noListener == false) {
+    options.parentDb = this;
+  }
+
   // Add promiseLibrary
   options.promiseLibrary = this.s.promiseLibrary;
 
   // Return the db object
   var db = new Db(dbName, this.s.topology, options)
+
   // Add as child
-  this.addChild(db);    
-  
+  if(options.noListener == null || options.noListener == false) {
+    this.addChild(db);
+  }
+
+  // Add the db to the cache
+  this.s.dbCache[dbName] = db;
   // Return the database
   return db;
 };
 
+define.classMethod('db', {callback: false, promise:false, returns: [Db]});
+
 var _executeAuthCreateUserCommand = function(self, username, password, options, callback) {
   // Special case where there is no password ($external users)
   if(typeof username == 'string'
@@ -1066,6 +1175,8 @@ var _executeAuthCreateUserCommand = function(self, username, password, options,
 }
 
 var addUser = function(self, username, password, options, callback) {
+  // Did the user destroy the topology
+  if(self.serverConfig && self.serverConfig.isDestroyed()) return callback(new MongoError('topology was destroyed'));
   // Attempt to execute auth command
   _executeAuthCreateUserCommand(self, username, password, options, function(err, r) {
     // We need to perform the backward compatible insert operation
@@ -1108,7 +1219,7 @@ var addUser = function(self, username, password, options, callback) {
 
     if(err) return handleCallback(callback, err);
     handleCallback(callback, err, r);
-  }); 
+  });
 }
 
 /**
@@ -1122,7 +1233,7 @@ var addUser = function(self, username, password, options, callback) {
  * @param {boolean} [options.j=false] Specify a journal write concern.
  * @param {object} [options.customData=null] Custom data associated with the user (only Mongodb 2.6 or higher)
  * @param {object[]} [options.roles=null] Roles associated with the created user (only Mongodb 2.6 or higher)
- * @param {Db~resultCallback} callback The command result callback
+ * @param {Db~resultCallback} [callback] The command result callback
  * @return {Promise} returns Promise if no callback passed
  */
 Db.prototype.addUser = function(username, password, options, callback) {
@@ -1135,7 +1246,7 @@ Db.prototype.addUser = function(username, password, options, callback) {
 
   // If we have a callback fallback
   if(typeof callback == 'function') return addUser(self, username, password, options, callback);
-  
+
   // Return a promise
   return new this.s.promiseLibrary(function(resolve, reject) {
     addUser(self, username, password, options, function(err, r) {
@@ -1145,8 +1256,12 @@ Db.prototype.addUser = function(username, password, options, callback) {
   });
 };
 
+define.classMethod('addUser', {callback: true, promise:true});
+
 var _executeAuthRemoveUserCommand = function(self, username, options, callback) {
   if(typeof options == 'function') callback = options, options = {};
+  // Did the user destroy the topology
+  if(self.serverConfig && self.serverConfig.isDestroyed()) return callback(new MongoError('topology was destroyed'));
   // Get the error options
   var commandOptions = {writeCommand:true};
   if(options['dbName']) commandOptions.dbName = options['dbName'];
@@ -1200,9 +1315,11 @@ var removeUser = function(self, username, options, callback) {
 
     if(err) return handleCallback(callback, err);
     handleCallback(callback, err, result);
-  });  
+  });
 }
 
+define.classMethod('removeUser', {callback: true, promise:true});
+
 /**
  * Remove a user from a database
  * @method
@@ -1211,7 +1328,7 @@ var removeUser = function(self, username, options, callback) {
  * @param {(number|string)} [options.w=null] The write concern.
  * @param {number} [options.wtimeout=null] The write concern timeout.
  * @param {boolean} [options.j=false] Specify a journal write concern.
- * @param {Db~resultCallback} callback The command result callback
+ * @param {Db~resultCallback} [callback] The command result callback
  * @return {Promise} returns Promise if no callback passed
  */
 Db.prototype.removeUser = function(username, options, callback) {
@@ -1235,6 +1352,8 @@ Db.prototype.removeUser = function(username, options, callback) {
 };
 
 var authenticate = function(self, username, password, options, callback) {
+  // Did the user destroy the topology
+  if(self.serverConfig && self.serverConfig.isDestroyed()) return callback(new MongoError('topology was destroyed'));
   // the default db to authenticate against is 'self'
   // if authententicate is called from a retry context, it may be another one, like admin
   var authdb = options.authdb ? options.authdb : options.dbName;
@@ -1294,7 +1413,7 @@ var authenticate = function(self, username, password, options, callback) {
       _callback(null, true);
     });
   } else {
-    handleCallback(callback, new MongoError(f("authentication mechanism %s not supported", options.authMechanism), false));
+    handleCallback(callback, MongoError.create({message: f("authentication mechanism %s not supported", options.authMechanism), driver:true}));
   }
 }
 
@@ -1305,7 +1424,7 @@ var authenticate = function(self, username, password, options, callback) {
  * @param {string} [password] The password.
  * @param {object} [options=null] Optional settings.
  * @param {string} [options.authMechanism=MONGODB-CR] The authentication mechanism to use, GSSAPI, MONGODB-CR, MONGODB-X509, PLAIN
- * @param {Db~resultCallback} callback The command result callback
+ * @param {Db~resultCallback} [callback] The command result callback
  * @return {Promise} returns Promise if no callback passed
  */
 Db.prototype.authenticate = function(username, password, options, callback) {
@@ -1322,27 +1441,38 @@ Db.prototype.authenticate = function(username, password, options, callback) {
     && options.authMechanism != 'MONGODB-X509'
     && options.authMechanism != 'SCRAM-SHA-1'
     && options.authMechanism != 'PLAIN') {
-      return handleCallback(callback, new MongoError("only GSSAPI, PLAIN, MONGODB-X509, SCRAM-SHA-1 or MONGODB-CR is supported by authMechanism"));
+      return handleCallback(callback, MongoError.create({message: "only GSSAPI, PLAIN, MONGODB-X509, SCRAM-SHA-1 or MONGODB-CR is supported by authMechanism", driver:true}));
   }
 
   // If we have a callback fallback
-  if(typeof callback == 'function') return authenticate(self, username, password, options, callback);
-  
+  if(typeof callback == 'function') return authenticate(self, username, password, options, function(err, r) {
+    // Support failed auth method
+    if(err && err.message && err.message.indexOf('saslStart') != -1) err.code = 59;
+    // Reject error
+    if(err) return callback(err, r);
+    callback(null, r);
+  });
+
   // Return a promise
   return new this.s.promiseLibrary(function(resolve, reject) {
     authenticate(self, username, password, options, function(err, r) {
+      // Support failed auth method
+      if(err && err.message && err.message.indexOf('saslStart') != -1) err.code = 59;
+      // Reject error
       if(err) return reject(err);
       resolve(r);
     });
   });
 };
 
+define.classMethod('authenticate', {callback: true, promise:true});
+
 /**
  * Logout user from server, fire off on all connections and remove all auth info
  * @method
  * @param {object} [options=null] Optional settings.
  * @param {string} [options.dbName=null] Logout against different database than current.
- * @param {Db~resultCallback} callback The command result callback
+ * @param {Db~resultCallback} [callback] The command result callback
  * @return {Promise} returns Promise if no callback passed
  */
 Db.prototype.logout = function(options, callback) {
@@ -1363,6 +1493,8 @@ Db.prototype.logout = function(options, callback) {
 
   // Execute the command
   if(typeof callback == 'function') return this.command(cmd, options, function(err, result) {
+    // Did the user destroy the topology
+    if(self.serverConfig && self.serverConfig.isDestroyed()) return callback(new MongoError('topology was destroyed'));
     if(err) return handleCallback(callback, err, false);
     handleCallback(callback, null, true)
   });
@@ -1370,12 +1502,16 @@ Db.prototype.logout = function(options, callback) {
   // Return promise
   return new this.s.promiseLibrary(function(resolve, reject) {
     self.command(cmd, options, function(err, result) {
+      // Did the user destroy the topology
+      if(self.serverConfig && self.serverConfig.isDestroyed()) return reject(new MongoError('topology was destroyed'));
       if(err) return reject(err);
       resolve(true);
     });
   });
 }
 
+define.classMethod('logout', {callback: true, promise:true});
+
 // Figure out the read preference
 var getReadPreference = function(options, db) {
   if(options.readPreference) return options;
@@ -1390,7 +1526,7 @@ var getReadPreference = function(options, db) {
  * @param {object} [options=null] Optional settings.
  * @param {boolean} [options.full=false] Returns the full raw index information.
  * @param {(ReadPreference|string)} [options.readPreference=null] The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST).
- * @param {Db~resultCallback} callback The command result callback
+ * @param {Db~resultCallback} [callback] The command result callback
  * @return {Promise} returns Promise if no callback passed
  */
 Db.prototype.indexInformation = function(name, options, callback) {
@@ -1400,7 +1536,7 @@ Db.prototype.indexInformation = function(name, options, callback) {
 
   // If we have a callback fallback
   if(typeof callback == 'function') return indexInformation(self, name, options, callback);
-  
+
   // Return a promise
   return new this.s.promiseLibrary(function(resolve, reject) {
     indexInformation(self, name, options, function(err, r) {
@@ -1414,6 +1550,9 @@ var indexInformation = function(self, name, options, callback) {
     // If we specified full information
   var full = options['full'] == null ? false : options['full'];
 
+  // Did the user destroy the topology
+  if(self.serverConfig && self.serverConfig.isDestroyed()) return callback(new MongoError('topology was destroyed'));
+
   // Process all the results from the index command and collection
   var processResults = function(indexes) {
     // Contains all the information
@@ -1440,6 +1579,8 @@ var indexInformation = function(self, name, options, callback) {
   });
 }
 
+define.classMethod('indexInformation', {callback: true, promise:true});
+
 var createCreateIndexCommand = function(db, name, fieldOrSpec, options) {
   var indexParameters = parseIndexOptions(fieldOrSpec);
   var fieldHash = indexParameters.fieldHash;
@@ -1514,13 +1655,13 @@ var createIndexUsingCreateIndexes = function(self, name, fieldOrSpec, options, c
 
 // Validate the database name
 var validateDatabaseName = function(databaseName) {
-  if(typeof databaseName !== 'string') throw new MongoError("database name must be a string");
-  if(databaseName.length === 0) throw new MongoError("database name cannot be the empty string");
+  if(typeof databaseName !== 'string') throw MongoError.create({message: "database name must be a string", driver:true});
+  if(databaseName.length === 0) throw MongoError.create({message: "database name cannot be the empty string", driver:true});
   if(databaseName == '$external') return;
 
   var invalidChars = [" ", ".", "$", "/", "\\"];
   for(var i = 0; i < invalidChars.length; i++) {
-    if(databaseName.indexOf(invalidChars[i]) != -1) throw new MongoError("database names cannot contain the character '" + invalidChars[i] + "'");
+    if(databaseName.indexOf(invalidChars[i]) != -1) throw MongoError.create({message: "database names cannot contain the character '" + invalidChars[i] + "'", driver:true});
   }
 }
 
@@ -1558,13 +1699,17 @@ var createListener = function(self, e, object) {
 /**
  * Db close event
  *
+ * Emitted after a socket closed against a single server or mongos proxy.
+ *
  * @event Db#close
- * @type {object}
+ * @type {MongoError}
  */
 
 /**
  * Db authenticated event
  *
+ * Emitted after all server members in the topology (single server, replicaset or mongos) have successfully authenticated.
+ *
  * @event Db#authenticated
  * @type {object}
  */
@@ -1572,6 +1717,10 @@ var createListener = function(self, e, object) {
 /**
  * Db reconnect event
  *
+ *  * Server: Emitted when the driver has reconnected and re-authenticated.
+ *  * ReplicaSet: N/A
+ *  * Mongos: Emitted when the driver reconnects and re-authenticates successfully against a Mongos.
+ *
  * @event Db#reconnect
  * @type {object}
  */
@@ -1579,6 +1728,8 @@ var createListener = function(self, e, object) {
 /**
  * Db error event
  *
+ * Emitted after an error occurred against a single server or mongos proxy.
+ *
  * @event Db#error
  * @type {MongoError}
  */
@@ -1586,19 +1737,27 @@ var createListener = function(self, e, object) {
 /**
  * Db timeout event
  *
+ * Emitted after a socket timeout occurred against a single server or mongos proxy.
+ *
  * @event Db#timeout
- * @type {object}
+ * @type {MongoError}
  */
 
 /**
  * Db parseError event
  *
+ * The parseError event is emitted if the driver detects illegal or corrupt BSON being received from the server.
+ *
  * @event Db#parseError
- * @type {object}
+ * @type {MongoError}
  */
 
 /**
- * Db fullsetup event, emitted when all servers in the topology have been connected to.
+ * Db fullsetup event, emitted when all servers in the topology have been connected to at start up time.
+ *
+ * * Server: Emitted when the driver has connected to the single server and has authenticated.
+ * * ReplSet: Emitted after the driver has attempted to connect to all replicaset members.
+ * * Mongos: Emitted after the driver has attempted to connect to all mongos proxies.
  *
  * @event Db#fullsetup
  * @type {Db}