private

• index.js

  Mongoose#_applyPlugins(schema)

  Applies global plugins to schema.

  Parameters:

  • schema <Schema>

  show code

  Mongoose.prototype._applyPlugins = function (schema) {
    for (var i = 0, l = this.plugins.length; i < l; i++) {
      schema.plugin(this.plugins[i][0], this.plugins[i][1]);
    }
  }

  ---

  Mongoose#Collection()

  The Mongoose Collection constructor

  ---

  Mongoose#connect(uri(s), [options], [callback])

  Opens the default mongoose connection.

  Parameters:

  • uri(s) <String>
  • [options] <Object>
  • [callback] <Function>

  Returns:

  • <Mongoose> this

  See:

  • Mongoose#createConnection

  If arguments are passed, they are proxied to either Connection#open or Connection#openSet appropriately.

  Options passed take precedence over options included in connection strings.

  Example:

  mongoose.connect('mongodb://user:pass@localhost:port/database');
  // replica sets
  var uri = 'mongodb://user:pass@localhost:port/database,mongodb://anotherhost:port,mongodb://yetanother:port';
  mongoose.connect(uri);
  // with options
  mongoose.connect(uri, options);
  // connecting to multiple mongos
  var uri = 'mongodb://hostA:27501,hostB:27501';
  var opts = { mongos: true };
  mongoose.connect(uri, opts);

  show code

  Mongoose.prototype.connect = function () {
    var conn = this.connection;
    if (rgxReplSet.test(arguments[0])) {
      conn.openSet.apply(conn, arguments);
    } else {
      conn.open.apply(conn, arguments);
    }
    return this;
  };

  ---

  Mongoose#Connection()

  The Mongoose Connection constructor

  ---

  Mongoose#createConnection([uri], [options])

  Creates a Connection instance.

  Parameters:

  • [uri] <String> a mongodb:// URI
  • [options] <Object> options to pass to the driver

  Returns:

  • <Connection> the created Connection object

  See:

  • Connection#open
  • Connection#openSet

  Each connection instance maps to a single database. This method is helpful when mangaging multiple db connections.

  If arguments are passed, they are proxied to either Connection#open or Connection#openSet appropriately. This means we can pass db, server, and replset options to the driver. Note that the safe option specified in your schema will overwrite the safe db option specified here unless you set your schemas safe option to undefined. See this for more information.

  Options passed take precedence over options included in connection strings.

  Example:

  // with mongodb:// URI
  db = mongoose.createConnection('mongodb://user:pass@localhost:port/database');
  // and options
  var opts = { db: { native_parser: true }}
  db = mongoose.createConnection('mongodb://user:pass@localhost:port/database', opts);
  // replica sets
  db = mongoose.createConnection('mongodb://user:pass@localhost:port,anotherhost:port,yetanother:port/database');
  // and options
  var opts = { replset: { strategy: 'ping', rs_name: 'testSet' }}
  db = mongoose.createConnection('mongodb://user:pass@localhost:port,anotherhost:port,yetanother:port/database', opts);
  // with [host, database_name[, port] signature
  db = mongoose.createConnection('localhost', 'database', port)
  // and options
  var opts = { server: { auto_reconnect: false }, user: 'username', pass: 'mypassword' }
  db = mongoose.createConnection('localhost', 'database', port, opts)
  // initialize now, connect later
  db = mongoose.createConnection();
  db.open('localhost', 'database', port, [opts]);

  show code

  Mongoose.prototype.createConnection = function () {
    var conn = new Connection(this);
    this.connections.push(conn);
    if (arguments.length) {
      if (rgxReplSet.test(arguments[0])) {
        conn.openSet.apply(conn, arguments);
      } else {
        conn.open.apply(conn, arguments);
      }
    }
    return conn;
  };

  ---

  Mongoose#disconnect([fn])

  Disconnects all connections.

  Parameters:

  • [fn] <Function> called after all connection close.

  Returns:

  • <Mongoose> this

  show code

  Mongoose.prototype.disconnect = function (fn) {
    var count = this.connections.length
      , error
    this.connections.forEach(function(conn){
      conn.close(function(err){
        if (error) return;
        if (err) {
          error = err;
          if (fn) return fn(err);
          throw err;
        }
        if (fn)
          --count || fn();
      });
    });
    return this;
  };

  ---

  Mongoose#Document()

  The Mongoose Document constructor.

  ---

  Mongoose#Error()

  The MongooseError constructor.

  ---

  Mongoose#get(key)

  Gets mongoose options

  Parameters:

  • key <String>

  Example:

  mongoose.get('test') // returns the 'test' value

  ---

  Mongoose#model(name, [schema], [collection], [skipInit])

  Defines a model or retrieves it.

  Parameters:

  • name <String> model name
  • [schema] <Schema>
  • [collection] <String> name (optional, induced from model name)
  • [skipInit] <Boolean> whether to skip initialization (defaults to false)

  Models defined on the mongoose instance are available to all connection created by the same mongoose instance.

  Example:

  var mongoose = require('mongoose');
  // define an Actor model with this mongoose instance
  mongoose.model('Actor', new Schema({ name: String }));
  // create a new connection
  var conn = mongoose.createConnection(..);
  // retrieve the Actor model
  var Actor = conn.model('Actor');

  When no collection argument is passed, Mongoose produces a collection name by passing the model name to the utils.toCollectionName method. This method pluralizes the name. If you don’t like this behavior, either pass a collection name or set your schemas collection name option.

  Example:

  var schema = new Schema({ name: String }, { collection: 'actor' });
  // or
  schema.set('collection', 'actor');
  // or
  var collectionName = 'actor'
  var M = mongoose.model('Actor', schema, collectionName)

  show code

  ``` Mongoose.prototype.model = function (name, schema, collection, skipInit) { if (‘string’ == typeof schema) {

  collection = schema;
  schema = false;

  }

  if (utils.isObject(schema) && !(schema instanceof Schema)) {

  schema = new Schema(schema);

  }

  if (‘boolean’ === typeof collection) {

  skipInit = collection;
  collection = null;

  }

  // handle internal options from connection.model() var options; if (skipInit && utils.isObject(skipInit)) {

  options = skipInit;
  skipInit = true;

  } else {

  options = {};

  }

  // look up schema for the collection. this might be a // default schema like system.indexes stored in SchemaDefaults. if (!this.modelSchemas[name]) {

  if (!schema && name in SchemaDefaults) {
    schema = SchemaDefaults[name];
  }
  if (schema) {
    // cache it so we only apply plugins once
    this.modelSchemas[name] = schema;
    this._applyPlugins(schema);
  } else {
    throw new mongoose.Error.MissingSchemaError(name);
  }

  }

  var model; var sub;

  // connection.model() may be passing a different schema for // an existing model name. in this case don’t read from cache. if (this.models[name] && false !== options.cache) {

  if (schema instanceof Schema && schema != this.models[name].schema) {
    throw new mongoose.Error.OverwriteModelError(name);
  }
  if (collection) {
    // subclass current model with alternate collection
    model = this.models[name];
    schema = model.prototype.schema;
    sub = model.__subclass(this.connection, schema, collection);
    // do not cache the sub model
    return sub;
  }
  return this.models[name];

  }

  // ensure a schema exists if (!schema) {

  schema = this.modelSchemas[name];
  if (!schema) {
    throw new mongoose.Error.MissingSchemaError(name);
  }

  }

  // Apply relevant “global” options to the schema if (!(‘pluralization’ in schema.options)) schema.options.pluralization = this.options.pluralization;

  if (!collection) {
    collection = schema.get('collection') || format(name, schema.options);
  }
  var connection = options.connection || this.connection;
  model = Model.compile(name, schema, collection, connection, this);
  if (!skipInit) {
    model.init();
  }
  if (false === options.cache) {
    return model;
  }
  return this.models[name] = model;
}
```
---
### [Mongoose#Model()](#index_Mongoose-Model)
The Mongoose [Model](#model_Model) constructor.
---
### [Mongoose#modelNames()](#index_Mongoose-modelNames)
Returns an array of model names created on this instance of Mongoose.
#### Returns:
-   <[Array](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array)>
#### Note:
*Does not include names of models created using `connection.model()`.*
show code
```
Mongoose.prototype.modelNames = function () {
  var names = Object.keys(this.models);
  return names;
}
```
---
### [Mongoose()](#index_Mongoose)
Mongoose constructor.
The exports object of the `mongoose` module is an instance of this class.  
Most apps will only use this one instance.
show code
```
function Mongoose () {
  this.connections = [];
  this.plugins = [];
  this.models = {};
  this.modelSchemas = {};
  // default global options
  this.options = {
    pluralization: true
  };
  var conn = this.createConnection(); // default connection
  conn.models = this.models;
};
```
---
### [Mongoose#Mongoose()](#index_Mongoose-Mongoose)
The Mongoose constructor
The exports of the mongoose module is an instance of this class.
#### Example:
```
var mongoose = require('mongoose');
var mongoose2 = new mongoose.Mongoose();
```
---
### [Mongoose#plugin(`fn`, `[opts]`)](#index_Mongoose-plugin)
Declares a global plugin executed on all Schemas.
#### Parameters:
-   `fn` <[Function](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Function)> plugin callback
-   `[opts]` <[Object](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object)> optional options
#### Returns:
-   <[Mongoose](#index_Mongoose)> this
#### See:
-   [plugins]($ed3b83fd8960771d.md "plugins")
Equivalent to calling `.plugin(fn)` on each Schema you create.
show code
```
Mongoose.prototype.plugin = function (fn, opts) {
  this.plugins.push([fn, opts]);
  return this;
};
```
---
### [Mongoose#Promise()](#index_Mongoose-Promise)
The Mongoose [Promise](#promise_Promise) constructor.
---
### [Mongoose#Query()](#index_Mongoose-Query)
The Mongoose [Query](#query_Query) constructor.
---
### [Mongoose#Schema()](#index_Mongoose-Schema)
The Mongoose [Schema](#schema_Schema) constructor
#### Example:
```
var mongoose = require('mongoose');
var Schema = mongoose.Schema;
var CatSchema = new Schema(..);
```
---
### [Mongoose#SchemaType()](#index_Mongoose-SchemaType)
The Mongoose [SchemaType](#schematype_SchemaType) constructor
---
### [Mongoose#set(`key`, `value`)](#index_Mongoose-set)
Sets mongoose options
#### Parameters:
-   `key` <[String](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String)>
-   `value` <[String](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String)>
#### Example:
```
mongoose.set('test', value) // sets the 'test' option to `value`
mongoose.set('debug', true) // enable logging collection methods + arguments to the console
```
show code
```
Mongoose.prototype.set = function (key, value) {
  if (arguments.length == 1) {
    return this.options[key];
  }
  this.options[key] = value;
  return this;
};
```
---
### [()](#index_)
Expose connection states for user-land
show code
```
Mongoose.prototype.STATES = STATES;
```
---
### [Mongoose#VirtualType()](#index_Mongoose-VirtualType)
The Mongoose [VirtualType](#virtualtype_VirtualType) constructor
---
### [Mongoose#connection](#index_Mongoose-connection)
The default connection of the mongoose module.
#### Example:
```
var mongoose = require('mongoose');
mongoose.connect(...);
mongoose.connection.on('error', cb);
```
This is the connection used by default for every model created using [mongoose.model](#index_Mongoose-model).
show code
```
Mongoose.prototype.__defineGetter__('connection', function(){
  return this.connections[0];
});
```
#### Returns:
-   <[Connection](#connection_Connection)>
---
### [Mongoose#mongo](#index_Mongoose-mongo)
The [node-mongodb-native](https://github.com/mongodb/node-mongodb-native) driver Mongoose uses.
show code
```
Mongoose.prototype.mongo = require('mongodb');
```
---
### [Mongoose#mquery](#index_Mongoose-mquery)
The [mquery](https://github.com/aheckmann/mquery) query builder Mongoose uses.
show code
```
Mongoose.prototype.mquery = require('mquery');
// Hack for Automattic/mongoose#2864
delete Mongoose.prototype.mquery.then;
```
---
### [Mongoose#SchemaTypes](#index_Mongoose-SchemaTypes)
The various Mongoose SchemaTypes.
#### Note:
*Alias of mongoose.Schema.Types for backwards compatibility.*
show code
```
Mongoose.prototype.SchemaTypes = Schema.Types;
```
#### See:
-   [Schema.SchemaTypes](#schema_Schema.Types "Schema.SchemaTypes")
---
### [Mongoose#Types](#index_Mongoose-Types)
The various Mongoose Types.
#### Example:
```
var mongoose = require('mongoose');
var array = mongoose.Types.Array;
```
#### Types:
-   [ObjectId](#types-objectid-js)
-   [Buffer](#types-buffer-js)
-   [SubDocument](#types-embedded-js)
-   [Array](#types-array-js)
-   [DocumentArray](#types-documentarray-js)
Using this exposed access to the `ObjectId` type, we can construct ids on demand.
```
var ObjectId = mongoose.Types.ObjectId;
var id1 = new ObjectId;
```
show code
```
Mongoose.prototype.Types = Types;
```
---
### [Mongoose#version](#index_Mongoose-version)
The Mongoose version
show code
```
Mongoose.prototype.version = pkg.version;
```
---

• querystream.js

  QueryStream#__next()

  Pulls the next doc from the cursor.

  See:

  • QueryStream#_next

  show code

  QueryStream.prototype.__next = function () {
    if (this.paused || this._destroyed)
      return this._running = false;
    var self = this;
    self._inline = T_INIT;
    self._cursor.nextObject(function cursorcb (err, doc) {
      self._onNextObject(err, doc);
    });
    // if onNextObject() was already called in this tick
    // return ourselves to the trampoline.
    if (T_CONT === this._inline) {
      return true;
    } else {
      // onNextObject() hasn't fired yet. tell onNextObject
      // that its ok to call _next b/c we are not within
      // the trampoline anymore.
      this._inline = T_IDLE;
    }
  }

  ---

  QueryStream#_init()

  Initializes the query.

  show code

  QueryStream.prototype._init = function () {
    if (this._destroyed) return;
    var query = this.query
      , model = query.model
      , options = query._optionsForExec(model)
      , self = this
    try {
      query.cast(model);
    } catch (err) {
      return self.destroy(err);
    }
    self._fields = utils.clone(query._fields);
    options.fields = query._castFields(self._fields);
    model.collection.find(query._conditions, options, function (err, cursor) {
      if (err) return self.destroy(err);
      self._cursor = cursor;
      self._next();
    });
  }

  ---

  QueryStream#_next()

  Trampoline for pulling the next doc from cursor.

  See:

  • QueryStream#__next

  show code

  QueryStream.prototype._next = function _next () {
    if (this.paused || this._destroyed) {
      return this._running = false;
    }
    this._running = true;
    if (this._buffer && this._buffer.length) {
      var arg;
      while (!this.paused && !this._destroyed && (arg = this._buffer.shift())) {
        this._onNextObject.apply(this, arg);
      }
    }
    // avoid stack overflows with large result sets.
    // trampoline instead of recursion.
    while (this.__next()) {}
  }

  ---

  QueryStream#_onNextObject(err, doc)

  Transforms raw docs returned from the cursor into a model instance.

  Parameters:

  • err <Error, null>
  • doc <Object>

  show code

  QueryStream.prototype._onNextObject = function _onNextObject (err, doc) {
    if (this._destroyed) return;
    if (this.paused) {
      this._buffer || (this._buffer = []);
      this._buffer.push([err, doc]);
      return this._running = false;
    }
    if (err) return this.destroy(err);
    // when doc is null we hit the end of the cursor
    if (!doc) {
      this.emit('end');
      return this.destroy();
    }
    var opts = this.query._mongooseOptions;
    if (!opts.populate) {
      return true === opts.lean
        ? emit(this, doc)
        : createAndEmit(this, doc);
    }
    var self = this;
    var pop = helpers.preparePopulationOptionsMQ(self.query, self.query._mongooseOptions);
    self.query.model.populate(doc, pop, function (err, doc) {
      if (err) return self.destroy(err);
      return true === opts.lean
        ? emit(self, doc)
        : createAndEmit(self, doc);
    })
  }
  function createAndEmit (self, doc) {
    var instance = helpers.createModel(self.query.model, doc, self._fields);
    instance.init(doc, function (err) {
      if (err) return self.destroy(err);
      emit(self, instance);
    });
  }

  ---

  QueryStream#destroy([err])

  Destroys the stream, closing the underlying cursor. No more events will be emitted.

  Parameters:

  • [err] <Error>

  show code

  QueryStream.prototype.destroy = function (err) {
    if (this._destroyed) return;
    this._destroyed = true;
    this._running = false;
    this.readable = false;
    if (this._cursor) {
      this._cursor.close();
    }
    if (err) {
      this.emit('error', err);
    }
    this.emit('close');
  }

  ---

  QueryStream#pause()

  Pauses this stream.

  show code

  QueryStream.prototype.pause = function () {
    this.paused = true;
  }

  ---

  QueryStream#pipe()

  Pipes this query stream into another stream. This method is inherited from NodeJS Streams.

  See:

  • NodeJS

  Example:

  query.stream().pipe(writeStream [, options])

  ---

  QueryStream(query, [options])

  Provides a Node.js 0.8 style ReadStream interface for Queries.

  Parameters:

  • query <Query>
  • [options] <Object>

  Inherits:

  • NodeJS Stream

  Events:

  • data: emits a single Mongoose document

  • error: emits when an error occurs during streaming. This will emit before the close event.

  • close: emits when the stream reaches the end of the cursor or an error occurs, or the stream is manually destroyed. After this event, no more events are emitted.

  var stream = Model.find().stream();
  stream.on('data', function (doc) {
    // do something with the mongoose document
  }).on('error', function (err) {
    // handle the error
  }).on('close', function () {
    // the stream is closed
  });

  The stream interface allows us to simply “plug-in” to other Node.js 0.8 style write streams.

  Model.where('created').gte(twoWeeksAgo).stream().pipe(writeStream);

  Valid options

  • transform: optional function which accepts a mongoose document. The return value of the function will be emitted on data.

  Example

  // JSON.stringify all documents before emitting
  var stream = Thing.find().stream({ transform: JSON.stringify });
  stream.pipe(writeStream);

  NOTE: plugging into an HTTP response will \not* work out of the box. Those streams expect only strings or buffers to be emitted, so first formatting our documents as strings/buffers is necessary.*

  NOTE: these streams are Node.js 0.8 style read streams which differ from Node.js 0.10 style. Node.js 0.10 streams are not well tested yet and are not guaranteed to work.

  show code

  function QueryStream (query, options) {
    Stream.call(this);
    this.query = query;
    this.readable = true;
    this.paused = false;
    this._cursor = null;
    this._destroyed = null;
    this._fields = null;
    this._buffer = null;
    this._inline = T_INIT;
    this._running = false;
    this._transform = options && 'function' == typeof options.transform
      ? options.transform
      : K;
    // give time to hook up events
    var self = this;
    process.nextTick(function () {
      self._init();
    });
  }

  ---

  QueryStream#resume()

  Resumes this stream.

  show code

  QueryStream.prototype.resume = function () {
    this.paused = false;
    if (!this._cursor) {
      // cannot start if not initialized
      return;
    }
    // are we within the trampoline?
    if (T_INIT === this._inline) {
      return;
    }
    if (!this._running) {
      // outside QueryStream control, need manual restart
      return this._next();
    }
  }

  ---

  QueryStream#paused

  Flag stating whether or not this stream is paused.

  show code

  QueryStream.prototype.paused;
  // trampoline flags
  var T_INIT = 0;
  var T_IDLE = 1;
  var T_CONT = 2;

  ---

  QueryStream#readable

  Flag stating whether or not this stream is readable.

  show code

  QueryStream.prototype.readable;

  ---

• connection.js

  Connection(base)

  Connection constructor

  Parameters:

  • base <Mongoose> a mongoose instance

  Inherits:

  • NodeJS EventEmitter

  Events:

  • connecting: Emitted when connection.{open,openSet}() is executed on this connection.

  • connected: Emitted when this connection successfully connects to the db. May be emitted multiple times in reconnected scenarios.

  • open: Emitted after we connected and onOpen is executed on all of this connections models.

  • disconnecting: Emitted when connection.close() was executed.

  • disconnected: Emitted after getting disconnected from the db.

  • close: Emitted after we disconnected and onClose executed on all of this connections models.

  • reconnected: Emitted after we connected and subsequently disconnected, followed by successfully another successfull connection.

  • error: Emitted when an error occurs on this connection.

  • fullsetup: Emitted in a replica-set scenario, when all nodes specified in the connection string are connected.

  For practical reasons, a Connection equals a Db.

  show code

  function Connection (base) {
    this.base = base;
    this.collections = {};
    this.models = {};
    this.replica = false;
    this.hosts = null;
    this.host = null;
    this.port = null;
    this.user = null;
    this.pass = null;
    this.name = null;
    this.options = null;
    this.otherDbs = [];
    this._readyState = STATES.disconnected;
    this._closeCalled = false;
    this._hasOpened = false;
  };

  ---

  Connection#open(connection_string, [database], [port], [options], [callback])

  Opens the connection to MongoDB.

  Parameters:

  • connection_string <String> mongodb://uri or the host to which you are connecting
  • [database] <String> database name
  • [port] <Number> database port
  • [options] <Object> options
  • [callback] <Function>

  See:

  • node-mongodb-native
  • http://mongodb.github.com/node-mongodb-native/api-generated/db.html#authenticate

  options is a hash with the following possible properties:

  db      - passed to the connection db instance
  server  - passed to the connection server instance(s)
  replset - passed to the connection ReplSet instance
  user    - username for authentication
  pass    - password for authentication
  auth    - options for authentication (see http://mongodb.github.com/node-mongodb-native/api-generated/db.html#authenticate)

  Notes:

  Mongoose forces the db option forceServerObjectId false and cannot be overridden.
  Mongoose defaults the server auto_reconnect options to true which can be overridden.
  See the node-mongodb-native driver instance for options that it understands.

  Options passed take precedence over options included in connection strings.

  show code

  Connection.prototype.open = function (host, database, port, options, callback) {
    var self = this
      , parsed
      , uri;
    if ('string' === typeof database) {
      switch (arguments.length) {
        case 2:
          port = 27017;
        case 3:
          switch (typeof port) {
            case 'function':
              callback = port, port = 27017;
              break;
            case 'object':
              options = port, port = 27017;
              break;
          }
          break;
        case 4:
          if ('function' === typeof options)
            callback = options, options = {};
      }
    } else {
      switch (typeof database) {
        case 'function':
          callback = database, database = undefined;
          break;
        case 'object':
          options = database;
          database = undefined;
          callback = port;
          break;
      }
      if (!rgxProtocol.test(host)) {
        host = 'mongodb://' + host;
      }
      try {
        parsed = muri(host);
      } catch (err) {
        this.error(err, callback);
        return this;
      }
      database = parsed.db;
      host = parsed.hosts[0].host || parsed.hosts[0].ipc;
      port = parsed.hosts[0].port || 27017;
    }
    this.options = this.parseOptions(options, parsed && parsed.options);
    // make sure we can open
    if (STATES.disconnected !== this.readyState) {
      var err = new Error('Trying to open unclosed connection.');
      err.state = this.readyState;
      this.error(err, callback);
      return this;
    }
    if (!host) {
      this.error(new Error('Missing hostname.'), callback);
      return this;
    }
    if (!database) {
      this.error(new Error('Missing database name.'), callback);
      return this;
    }
    // authentication
    if (options && options.user && options.pass) {
      this.user = options.user;
      this.pass = options.pass;
    } else if (parsed && parsed.auth) {
      this.user = parsed.auth.user;
      this.pass = parsed.auth.pass;
    // Check hostname for user/pass
    } else if (/@/.test(host) && /:/.test(host.split('@')[0])) {
      host = host.split('@');
      var auth = host.shift().split(':');
      host = host.pop();
      this.user = auth[0];
      this.pass = auth[1];
    } else {
      this.user = this.pass = undefined;
    }
    this.name = database;
    this.host = host;
    this.port = port;
    this._open(callback);
    return this;
  };

  ---

  Connection#openSet(uris, [database], [options], [callback])

  Opens the connection to a replica set.

  Parameters:

  • uris <String> comma-separated mongodb:// `URI`s
  • [database] <String> database name if not included in `uris`
  • [options] <Object> passed to the internal driver
  • [callback] <Function>

  See:

  • node-mongodb-native
  • http://mongodb.github.com/node-mongodb-native/api-generated/db.html#authenticate

  Example:

  var db = mongoose.createConnection();
  db.openSet("mongodb://user:pwd@localhost:27020/testing,mongodb://example.com:27020,mongodb://localhost:27019");

  The database name and/or auth need only be included in one URI.
  The options is a hash which is passed to the internal driver connection object.

  Valid options

  db      - passed to the connection db instance
  server  - passed to the connection server instance(s)
  replset - passed to the connection ReplSetServer instance
  user    - username for authentication
  pass    - password for authentication
  auth    - options for authentication (see http://mongodb.github.com/node-mongodb-native/api-generated/db.html#authenticate)
  mongos  - Boolean - if true, enables High Availability support for mongos

  Options passed take precedence over options included in connection strings.

  Notes:

  If connecting to multiple mongos servers, set the mongos option to true.

  conn.open('mongodb://mongosA:27501,mongosB:27501', { mongos: true }, cb);

  Mongoose forces the db option forceServerObjectId false and cannot be overridden.
  Mongoose defaults the server auto_reconnect options to true which can be overridden.
  See the node-mongodb-native driver instance for options that it understands.

  Options passed take precedence over options included in connection strings.

  show code

  Connection.prototype.openSet = function (uris, database, options, callback) {
    if (!rgxProtocol.test(uris)) {
      uris = 'mongodb://' + uris;
    }
    var self = this;
    switch (arguments.length) {
      case 3:
        switch (typeof database) {
          case 'string':
            this.name = database;
            break;
          case 'object':
            callback = options;
            options = database;
            database = null;
            break;
        }
        if ('function' === typeof options) {
          callback = options;
          options = {};
        }
        break;
      case 2:
        switch (typeof database) {
          case 'string':
            this.name = database;
            break;
          case 'function':
            callback = database, database = null;
            break;
          case 'object':
            options = database, database = null;
            break;
        }
    }
    var parsed;
    try {
      parsed = muri(uris);
    } catch (err) {
      this.error(err, callback);
      return this;
    }
    if (!this.name) {
      this.name = parsed.db;
    }
    this.hosts = parsed.hosts;
    this.options = this.parseOptions(options, parsed && parsed.options);
    this.replica = true;
    if (!this.name) {
      this.error(new Error('No database name provided for replica set'), callback);
      return this;
    }
    // authentication
    if (options && options.user && options.pass) {
      this.user = options.user;
      this.pass = options.pass;
    } else if (parsed && parsed.auth) {
      this.user = parsed.auth.user;
      this.pass = parsed.auth.pass;
    } else {
      this.user = this.pass = undefined;
    }
    this._open(callback);
    return this;
  };

  ---

  Connection#error(err, callback)

  error

  Parameters:

  • err <Error>
  • callback <Function> optional

  Graceful error handling, passes error to callback
  if available, else emits error on the connection.

  show code

  Connection.prototype.error = function (err, callback) {
    if (callback) return callback(err);
    this.emit('error', err);
  }

  ---

  Connection#_open(callback)

  Handles opening the connection with the appropriate method based on connection type.

  Parameters:

  • callback <Function>

  show code

  Connection.prototype._open = function (callback) {
    this.readyState = STATES.connecting;
    this._closeCalled = false;
    var self = this;
    var method = this.replica
      ? 'doOpenSet'
      : 'doOpen';
    // open connection
    this[method](function (err) {
      if (err) {
        self.readyState = STATES.disconnected;
        if (self._hasOpened) {
          if (callback) callback(err);
        } else {
          self.error(err, callback);
        }
        return;
      }
      self.onOpen(callback);
    });
  }

  ---

  Connection#onOpen()

  Called when the connection is opened

  show code

  Connection.prototype.onOpen = function (callback) {
    var self = this;
    function open(err, isAuth) {
      if (err) {
        self.readyState = isAuth ? STATES.unauthorized : STATES.disconnected;
        if (self._hasOpened) {
          if (callback) callback(err);
        } else {
          self.error(err, callback);
        }
        return;
      }
      self.readyState = STATES.connected;
      // avoid having the collection subscribe to our event emitter
      // to prevent 0.3 warning
      for (var i in self.collections)
        self.collections[i].onOpen();
      callback && callback();
      self.emit('open');
    };
    // re-authenticate
    if (self.user && self.pass) {
      self.db.authenticate(self.user, self.pass, self.options.auth, function(err) {
        open(err, true);
      });
    } else {
      open();
    }
  };

  ---

  Connection#close([callback])

  Closes the connection

  Parameters:

  • [callback] <Function> optional

  Returns:

  • <Connection> self

  show code

  Connection.prototype.close = function (callback) {
    var self = this;
    this._closeCalled = true;
    switch (this.readyState){
      case 0: // disconnected
        callback && callback();
        break;
      case 1: // connected
      case 4: // unauthorized
        this.readyState = STATES.disconnecting;
        this.doClose(function(err){
          if (err){
            self.error(err, callback);
          } else {
            self.onClose();
            callback && callback();
          }
        });
        break;
      case 2: // connecting
        this.once('open', function(){
          self.close(callback);
        });
        break;
      case 3: // disconnecting
        if (!callback) break;
        this.once('close', function () {
          callback();
        });
        break;
    }
    return this;
  };

  ---

  Connection#onClose()

  Called when the connection closes

  show code

  Connection.prototype.onClose = function () {
    this.readyState = STATES.disconnected;
    // avoid having the collection subscribe to our event emitter
    // to prevent 0.3 warning
    for (var i in this.collections)
      this.collections[i].onClose();
    this.emit('close');
  };

  ---

  Connection#collection(name, [options])

  Retrieves a collection, creating it if not cached.

  Parameters:

  • name <String> of the collection
  • [options] <Object> optional collection options

  Returns:

  • <Collection> collection instance

  Not typically needed by applications. Just talk to your collection through your model.

  show code

  Connection.prototype.collection = function (name, options) {
    if (!(name in this.collections))
      this.collections[name] = new Collection(name, this, options);
    return this.collections[name];
  };

  ---

  Connection#model(name, [schema], [collection])

  Defines or retrieves a model.

  Parameters:

  • name <String> the model name
  • [schema] <Schema> a schema. necessary when defining a model
  • [collection] <String> name of mongodb collection (optional) if not given it will be induced from model name

  Returns:

  • <Model> The compiled model

  See:

  • Mongoose#model

  var mongoose = require('mongoose');
  var db = mongoose.createConnection(..);
  db.model('Venue', new Schema(..));
  var Ticket = db.model('Ticket', new Schema(..));
  var Venue = db.model('Venue');

  When no collection argument is passed, Mongoose produces a collection name by passing the model name to the utils.toCollectionName method. This method pluralizes the name. If you don’t like this behavior, either pass a collection name or set your schemas collection name option.

  Example:

  var schema = new Schema({ name: String }, { collection: 'actor' });
  // or
  schema.set('collection', 'actor');
  // or
  var collectionName = 'actor'
  var M = conn.model('Actor', schema, collectionName)

  show code

  Connection.prototype.model = function (name, schema, collection) {
    // collection name discovery
    if ('string' == typeof schema) {
      collection = schema;
      schema = false;
    }
    if (utils.isObject(schema) && !(schema instanceof Schema)) {
      schema = new Schema(schema);
    }
    if (this.models[name] && !collection) {
      // model exists but we are not subclassing with custom collection
      if (schema instanceof Schema && schema != this.models[name].schema) {
        throw new MongooseError.OverwriteModelError(name);
      }
      return this.models[name];
    }
    var opts = { cache: false, connection: this }
    var model;
    if (schema instanceof Schema) {
      // compile a model
      model = this.base.model(name, schema, collection, opts)
      // only the first model with this name is cached to allow
      // for one-offs with custom collection names etc.
      if (!this.models[name]) {
        this.models[name] = model;
      }
      model.init();
      return model;
    }
    if (this.models[name] && collection) {
      // subclassing current model with alternate collection
      model = this.models[name];
      schema = model.prototype.schema;
      var sub = model.__subclass(this, schema, collection);
      // do not cache the sub model
      return sub;
    }
    // lookup model in mongoose module
    model = this.base.models[name];
    if (!model) {
      throw new MongooseError.MissingSchemaError(name);
    }
    if (this == model.prototype.db
        && (!collection || collection == model.collection.name)) {
      // model already uses this connection.
      // only the first model with this name is cached to allow
      // for one-offs with custom collection names etc.
      if (!this.models[name]) {
        this.models[name] = model;
      }
      return model;
    }
    return this.models[name] = model.__subclass(this, schema, collection);
  }

  ---

  Connection#modelNames()

  Returns an array of model names created on this connection.

  Returns:

  • <Array>

  show code

  Connection.prototype.modelNames = function () {
    return Object.keys(this.models);
  }

  ---

  Connection#setProfiling(level, [ms], callback)

  Set profiling level.

  Parameters:

  • level <Number, String> either off (0), slow (1), or all (2)
  • [ms] <Number> the threshold in milliseconds above which queries will be logged when in `slow` mode. defaults to 100.
  • callback <Function>

  show code

  Connection.prototype.setProfiling = function (level, ms, callback) {
    if (STATES.connected !== this.readyState) {
      return this.on('open', this.setProfiling.bind(this, level, ms, callback));
    }
    if (!callback) callback = ms, ms = 100;
    var cmd = {};
    switch (level) {
      case 0:
      case 'off':
        cmd.profile = 0;
        break;
      case 1:
      case 'slow':
        cmd.profile = 1;
        if ('number' !== typeof ms) {
          ms = parseInt(ms, 10);
          if (isNaN(ms)) ms = 100;
        }
        cmd.slowms = ms;
        break;
      case 2:
      case 'all':
        cmd.profile = 2;
        break;
      default:
        return callback(new Error('Invalid profiling level: '+ level));
    }
    this.db.executeDbCommand(cmd, function (err, resp) {
      if (err) return callback(err);
      var doc = resp.documents[0];
      err = 1 === doc.ok
        ? null
        : new Error('Could not set profiling level to: '+ level)
      callback(err, doc);
    });
  };

  ---

  Connection#db

  The mongodb.Db instance, set when the connection is opened

  show code

  Connection.prototype.db;

  ---

  Connection#collections

  A hash of the collections associated with this connection

  show code

  Connection.prototype.collections;

  ---

  Connection#readyState

  Connection ready state

  • 0 = disconnected
  • 1 = connected
  • 2 = connecting
  • 3 = disconnecting

  Each state change emits its associated event name.

  Example

  conn.on('connected', callback);
  conn.on('disconnected', callback);

  show code

  Object.defineProperty(Connection.prototype, 'readyState', {
      get: function(){ return this._readyState; }
    , set: function (val) {
        if (!(val in STATES)) {
          throw new Error('Invalid connection state: ' + val);
        }
        if (this._readyState !== val) {
          this._readyState = val;
          // loop over the otherDbs on this connection and change their state
          for (var i=0; i < this.otherDbs.length; i++) {
            this.otherDbs[i].readyState = val;
          }
          if (STATES.connected === val)
            this._hasOpened = true;
          this.emit(STATES[val]);
        }
      }
  });

  ---

• utils.js

  exports.mergeClone(to, from)

  merges to with a copy of from

  show code

  exports.mergeClone = function(to, from) {
    var keys = Object.keys(from)
      , i = keys.length
      , key
    while (i--) {
      key = keys[i];
      if ('undefined' === typeof to[key]) {
        // make sure to retain key order here because of a bug handling the $each
        // operator in mongodb 2.4.4
        to[key] = exports.clone(from[key], { retainKeyOrder : 1});
      } else {
        if (exports.isObject(from[key])) {
          exports.mergeClone(to[key], from[key]);
        } else {
          // make sure to retain key order here because of a bug handling the
          // $each operator in mongodb 2.4.4
          to[key] = exports.clone(from[key], { retainKeyOrder : 1});
        }
      }
    }
  }

  Parameters:

  • to <Object>
  • from <Object>

  ---

  exports.pluralization

  Pluralization rules.

  show code

  exports.pluralization = [
    [/(m)an$/gi, '$1en'],
    [/(pe)rson$/gi, '$1ople'],
    [/(child)$/gi, '$1ren'],
    [/^(ox)$/gi, '$1en'],
    [/(ax|test)is$/gi, '$1es'],
    [/(octop|vir)us$/gi, '$1i'],
    [/(alias|status)$/gi, '$1es'],
    [/(bu)s$/gi, '$1ses'],
    [/(buffal|tomat|potat)o$/gi, '$1oes'],
    [/([ti])um$/gi, '$1a'],
    [/sis$/gi, 'ses'],
    [/(?:([^f])fe|([lr])f)$/gi, '$1$2ves'],
    [/(hive)$/gi, '$1s'],
    [/([^aeiouy]|qu)y$/gi, '$1ies'],
    [/(x|ch|ss|sh)$/gi, '$1es'],
    [/(matr|vert|ind)ix|ex$/gi, '$1ices'],
    [/([m|l])ouse$/gi, '$1ice'],
    [/(quiz)$/gi, '$1zes'],
    [/s$/gi, 's'],
    [/([^a-z])$/, '$1'],
    [/$/gi, 's']
  ];
  var rules = exports.pluralization;

  These rules are applied while processing the argument to toCollectionName.

  ---

  exports.uncountables

  Uncountable words.

  show code

  exports.uncountables = [
    'advice',
    'energy',
    'excretion',
    'digestion',
    'cooperation',
    'health',
    'justice',
    'labour',
    'machinery',
    'equipment',
    'information',
    'pollution',
    'sewage',
    'paper',
    'money',
    'species',
    'series',
    'rain',
    'rice',
    'fish',
    'sheep',
    'moose',
    'deer',
    'news',
    'expertise',
    'status',
    'media'
  ];
  var uncountables = exports.uncountables;

  These words are applied while processing the argument to toCollectionName.

  ---

• drivers/node-mongodb-native/collection.js

  NativeCollection#getIndexes(callback)

  Retreives information about this collections indexes.

  Parameters:

  • callback <Function>

  ---

  NativeCollection()

  A node-mongodb-native collection implementation.

  Inherits:

  • Collection

  All methods methods from the node-mongodb-native driver are copied and wrapped in queue management.

  show code

  function NativeCollection () {
    this.collection = null;
    MongooseCollection.apply(this, arguments);
  }

  ---

  NativeCollection#onClose()

  Called when the connection closes

  show code

  NativeCollection.prototype.onClose = function () {
    MongooseCollection.prototype.onClose.call(this);
  };

  ---

  NativeCollection#onOpen()

  Called when the connection opens.

  show code

  NativeCollection.prototype.onOpen = function () {
    var self = this;
    // always get a new collection in case the user changed host:port
    // of parent db instance when re-opening the connection.
    if (!self.opts.capped.size) {
      // non-capped
      return self.conn.db.collection(self.name, callback);
    }
    // capped
    return self.conn.db.collection(self.name, function (err, c) {
      if (err) return callback(err);
      // discover if this collection exists and if it is capped
      self.conn.db.collection( 'system.namespaces', function(err, namespaces) {
        var namespaceName = self.conn.db.databaseName + '.' + self.name;
        namespaces.findOne({ name : namespaceName }, function(err, doc) {
          if (err) {
            return callback(err);
          }
          var exists = !!doc;
          if (exists) {
            if (doc.options && doc.options.capped) {
              callback(null, c);
            } else {
              var msg = 'A non-capped collection exists with the name: '+ self.name +'
  '
                      + ' To use this collection as a capped collection, please '
                      + 'first convert it.
  '
                      + ' http://www.mongodb.org/display/DOCS/Capped+Collections#CappedCollections-Convertingacollectiontocapped'
              err = new Error(msg);
              callback(err);
            }
          } else {
            // create
            var opts = utils.clone(self.opts.capped);
            opts.capped = true;
            self.conn.db.createCollection(self.name, opts, callback);
          }
        });
      });
    });
    function callback (err, collection) {
      if (err) {
        // likely a strict mode error
        self.conn.emit('error', err);
      } else {
        self.collection = collection;
        MongooseCollection.prototype.onOpen.call(self);
      }
    };
  };

  ---

• drivers/node-mongodb-native/connection.js

  NativeConnection#doClose(fn)

  Closes the connection

  Parameters:

  • fn <Function>

  Returns:

  • <Connection> this

  show code

  NativeConnection.prototype.doClose = function (fn) {
    this.db.close();
    if (fn) fn();
    return this;
  }

  ---

  NativeConnection#doOpen(fn)

  Opens the connection to MongoDB.

  Parameters:

  • fn <Function>

  Returns:

  • <Connection> this

  show code

  NativeConnection.prototype.doOpen = function (fn) {
    if (this.db) {
      mute(this);
    }
    var server = new Server(this.host, this.port, this.options.server);
    this.db = new Db(this.name, server, this.options.db);
    var self = this;
    this.db.open(function (err) {
      if (err) return fn(err);
      listen(self);
      fn();
    });
    return this;
  };

  ---

  NativeConnection#doOpenSet(fn)

  Opens a connection to a MongoDB ReplicaSet.

  Parameters:

  • fn <Function>

  Returns:

  • <Connection> this

  See description of doOpen for server options. In this case options.replset is also passed to ReplSetServers.

  show code

  NativeConnection.prototype.doOpenSet = function (fn) {
    if (this.db) {
      mute(this);
    }
    var servers = []
      , self = this;
    this.hosts.forEach(function (server) {
      var host = server.host || server.ipc;
      var port = server.port || 27017;
      servers.push(new Server(host, port, self.options.server));
    })
    var server = this.options.mongos
      ? new Mongos(servers, this.options.mongos)
      : new ReplSetServers(servers, this.options.replset);
    this.db = new Db(this.name, server, this.options.db);
    this.db.on('fullsetup', function () {
      self.emit('fullsetup')
    });
    this.db.open(function (err) {
      if (err) return fn(err);
      fn();
      listen(self);
    });
    return this;
  };

  ---

  NativeConnection()

  A node-mongodb-native connection implementation.

  Inherits:

  • Connection

  show code

  function NativeConnection() {
    MongooseConnection.apply(this, arguments);
    this._listening = false;
  };

  ---

  NativeConnection#parseOptions(passed, [connStrOptions])

  Prepares default connection options for the node-mongodb-native driver.

  Parameters:

  • passed <Object> options that were passed directly during connection
  • [connStrOptions] <Object> options that were passed in the connection string

  NOTE: passed options take precedence over connection string options.

  show code

  NativeConnection.prototype.parseOptions = function (passed, connStrOpts) {
    var o = passed || {};
    o.db || (o.db = {});
    o.auth || (o.auth = {});
    o.server || (o.server = {});
    o.replset || (o.replset = {});
    o.server.socketOptions || (o.server.socketOptions = {});
    o.replset.socketOptions || (o.replset.socketOptions = {});
    var opts = connStrOpts || {};
    Object.keys(opts).forEach(function (name) {
      switch (name) {
        case 'ssl':
        case 'poolSize':
          if ('undefined' == typeof o.server[name]) {
            o.server[name] = o.replset[name] = opts[name];
          }
          break;
        case 'slaveOk':
          if ('undefined' == typeof o.server.slave_ok) {
            o.server.slave_ok = opts[name];
          }
          break;
        case 'autoReconnect':
          if ('undefined' == typeof o.server.auto_reconnect) {
            o.server.auto_reconnect = opts[name];
          }
          break;
        case 'socketTimeoutMS':
        case 'connectTimeoutMS':
          if ('undefined' == typeof o.server.socketOptions[name]) {
            o.server.socketOptions[name] = o.replset.socketOptions[name] = opts[name];
          }
          break;
        case 'authdb':
          if ('undefined' == typeof o.auth.authdb) {
            o.auth.authdb = opts[name];
          }
          break;
        case 'authSource':
          if ('undefined' == typeof o.auth.authSource) {
            o.auth.authSource = opts[name];
          }
          break;
        case 'retries':
        case 'reconnectWait':
        case 'rs_name':
          if ('undefined' == typeof o.replset[name]) {
            o.replset[name] = opts[name];
          }
          break;
        case 'replicaSet':
          if ('undefined' == typeof o.replset.rs_name) {
            o.replset.rs_name = opts[name];
          }
          break;
        case 'readSecondary':
          if ('undefined' == typeof o.replset.read_secondary) {
            o.replset.read_secondary = opts[name];
          }
          break;
        case 'nativeParser':
          if ('undefined' == typeof o.db.native_parser) {
            o.db.native_parser = opts[name];
          }
          break;
        case 'w':
        case 'safe':
        case 'fsync':
        case 'journal':
        case 'wtimeoutMS':
          if ('undefined' == typeof o.db[name]) {
            o.db[name] = opts[name];
          }
          break;
        case 'readPreference':
          if ('undefined' == typeof o.db.read_preference) {
            o.db.read_preference = opts[name];
          }
          break;
        case 'readPreferenceTags':
          if ('undefined' == typeof o.db.read_preference_tags) {
            o.db.read_preference_tags = opts[name];
          }
          break;
      }
    })
    if (!('auto_reconnect' in o.server)) {
      o.server.auto_reconnect = true;
    }
    if (!o.db.read_preference) {
      // read from primaries by default
      o.db.read_preference = 'primary';
    }
    // mongoose creates its own ObjectIds
    o.db.forceServerObjectId = false;
    // default safe using new nomenclature
    if (!('journal' in o.db || 'j' in o.db ||
          'fsync' in o.db || 'safe' in o.db || 'w' in o.db)) {
      o.db.w = 1;
    }
    validate(o);
    return o;
  }

  ---

  NativeConnection#useDb(name)

  Switches to a different database using the same connection pool.

  Parameters:

  • name <String> The database name

  Returns:

  • <Connection> New Connection Object

  Returns a new connection object, with the new db.

  show code

  NativeConnection.prototype.useDb = function (name) {
    // we have to manually copy all of the attributes...
    var newConn = new this.constructor();
    newConn.name = name;
    newConn.base = this.base;
    newConn.collections = {};
    newConn.models = {};
    newConn.replica = this.replica;
    newConn.hosts = this.hosts;
    newConn.host = this.host;
    newConn.port = this.port;
    newConn.user = this.user;
    newConn.pass = this.pass;
    newConn.options = this.options;
    newConn._readyState = this._readyState;
    newConn._closeCalled = this._closeCalled;
    newConn._hasOpened = this._hasOpened;
    newConn._listening = false;
    // First, when we create another db object, we are not guaranteed to have a
    // db object to work with. So, in the case where we have a db object and it
    // is connected, we can just proceed with setting everything up. However, if
    // we do not have a db or the state is not connected, then we need to wait on
    // the 'open' event of the connection before doing the rest of the setup
    // the 'connected' event is the first time we'll have access to the db object
    var self = this;
    if (this.db && this.db._state == 'connected') {
      wireup();
    } else {
      this.once('connected', wireup);
    }
    function wireup () {
      newConn.db = self.db.db(name);
      newConn.onOpen();
      // setup the events appropriately
      listen(newConn);
    }
    newConn.name = name;
    // push onto the otherDbs stack, this is used when state changes
    this.otherDbs.push(newConn);
    newConn.otherDbs.push(this);
    return newConn;
  };

  ---

  NativeConnection.STATES

  Expose the possible connection states.

  show code

  NativeConnection.STATES = STATES;

  ---

• error/version.js

  VersionError()

  Version Error constructor.

  Inherits:

  • MongooseError

  show code

  function VersionError () {
    MongooseError.call(this, 'No matching document found.');
    Error.captureStackTrace(this, arguments.callee);
    this.name = 'VersionError';
  };

  ---

• error/messages.js

  MongooseError#messages

  The default built-in validator error messages. These may be customized.

  // customize within each schema or globally like so
  var mongoose = require('mongoose');
  mongoose.Error.messages.String.enum  = "Your custom message for {PATH}.";

  As you might have noticed, error messages support basic templating

  • {PATH} is replaced with the invalid document path
  • {VALUE} is replaced with the invalid value
  • {TYPE} is replaced with the validator type such as “regexp”, “min”, or “user defined”
  • {MIN} is replaced with the declared min value for the Number.min validator
  • {MAX} is replaced with the declared max value for the Number.max validator

  Click the “show code” link below to see all defaults.

  show code

  var msg = module.exports = exports = {};
  msg.general = {};
  msg.general.default = "Validator failed for path `{PATH}` with value `{VALUE}`";
  msg.general.required = "Path `{PATH}` is required.";
  msg.Number = {};
  msg.Number.min = "Path `{PATH}` ({VALUE}) is less than minimum allowed value ({MIN}).";
  msg.Number.max = "Path `{PATH}` ({VALUE}) is more than maximum allowed value ({MAX}).";
  msg.String = {};
  msg.String.enum = "`{VALUE}` is not a valid enum value for path `{PATH}`.";
  msg.String.match = "Path `{PATH}` is invalid ({VALUE}).";

  ---

• error/validation.js

  ValidationError#toString()

  Console.log helper

  show code

  ValidationError.prototype.toString = function () {
    var ret = this.name + ': ';
    var msgs = [];
    Object.keys(this.errors).forEach(function (key) {
      if (this == this.errors[key]) return;
      msgs.push(String(this.errors[key]));
    }, this)
    return ret + msgs.join(', ');
  };

  ---

  ValidationError(instance)

  Document Validation Error

  Parameters:

  • instance <Document>

  Inherits:

  • MongooseError

  show code

  function ValidationError (instance) {
    MongooseError.call(this, "Validation failed");
    Error.captureStackTrace(this, arguments.callee);
    this.name = 'ValidationError';
    this.errors = instance.errors = {};
  };

  ---

• error/cast.js

  CastError(type, value)

  Casting Error constructor.

  Parameters:

  • type <String>
  • value <String>

  Inherits:

  • MongooseError

  show code

  function CastError (type, value, path) {
    MongooseError.call(this, 'Cast to ' + type + ' failed for value "' + value + '" at path "' + path + '"');
    Error.captureStackTrace(this, arguments.callee);
    this.name = 'CastError';
    this.type = type;
    this.value = value;
    this.path = path;
  };

  ---

• error/validator.js

  ValidatorError(path, msg, val)

  Schema validator error

  Parameters:

  • path <String>
  • msg <String>
  • val <String, Number, T>

  Inherits:

  • MongooseError

  show code

  function ValidatorError (path, msg, type, val) {
    if (!msg) msg = errorMessages.general.default;
    var message = this.formatMessage(msg, path, type, val);
    MongooseError.call(this, message);
    Error.captureStackTrace(this, arguments.callee);
    this.name = 'ValidatorError';
    this.path = path;
    this.type = type;
    this.value = val;
  };

  ---

• error.js

  MongooseError(msg)

  MongooseError constructor

  Parameters:

  • msg <String> Error message

  Inherits:

  • Error

  show code

  function MongooseError (msg) {
    Error.call(this);
    Error.captureStackTrace(this, arguments.callee);
    this.message = msg;
    this.name = 'MongooseError';
  };

  ---

  MongooseError.messages

  The default built-in validator error messages.

  show code

  MongooseError.messages = require('./error/messages');
  // backward compat
  MongooseError.Messages = MongooseError.messages;

  See:

  • Error.messages

  ---

• virtualtype.js

  VirtualType#applyGetters(value, scope)

  Applies getters to value using optional scope.

  Parameters:

  • value <Object>
  • scope <Object>

  Returns:

  • <T> the value after applying all getters

  show code

  VirtualType.prototype.applyGetters = function (value, scope) {
    var v = value;
    for (var l = this.getters.length - 1; l >= 0; l--) {
      v = this.getters[l].call(scope, v, this);
    }
    return v;
  };

  ---

  VirtualType#applySetters(value, scope)

  Applies setters to value using optional scope.

  Parameters:

  • value <Object>
  • scope <Object>

  Returns:

  • <T> the value after applying all setters

  show code

  VirtualType.prototype.applySetters = function (value, scope) {
    var v = value;
    for (var l = this.setters.length - 1; l >= 0; l--) {
      v = this.setters[l].call(scope, v, this);
    }
    return v;
  };

  ---

  VirtualType#get(fn)

  Defines a getter.

  Parameters:

  • fn <Function>

  Returns:

  • <VirtualType> this

  Example:

  var virtual = schema.virtual('fullname');
  virtual.get(function () {
    return this.name.first + ' ' + this.name.last;
  });

  show code

  VirtualType.prototype.get = function (fn) {
    this.getters.push(fn);
    return this;
  };

  ---

  VirtualType#set(fn)

  Defines a setter.

  Parameters:

  • fn <Function>

  Returns:

  • <VirtualType> this

  Example:

  var virtual = schema.virtual('fullname');
  virtual.set(function (v) {
    var parts = v.split(' ');
    this.name.first = parts[0];
    this.name.last = parts[1];
  });

  show code

  VirtualType.prototype.set = function (fn) {
    this.setters.push(fn);
    return this;
  };

  ---

  VirtualType()

  VirtualType constructor

  This is what mongoose uses to define virtual attributes via Schema.prototype.virtual.

  Example:

  var fullname = schema.virtual('fullname');
  fullname instanceof mongoose.VirtualType // true

  show code

  function VirtualType (options, name) {
    this.path = name;
    this.getters = [];
    this.setters = [];
    this.options = options || {};
  }

  ---

• schema.js

  Schema#add(obj, prefix)

  Adds key path / schema type pairs to this schema.

  Parameters:

  • obj <Object>
  • prefix <String>

  Example:

  var ToySchema = new Schema;
  ToySchema.add({ name: 'string', color: 'string', price: 'number' });

  show code

  Schema.prototype.add = function add (obj, prefix) {
    prefix = prefix || '';
    var keys = Object.keys(obj);
    for (var i = 0; i < keys.length; ++i) {
      var key = keys[i];
      if (null == obj[key]) {
        throw new TypeError('Invalid value for schema path `'+ prefix + key +'`');
      }
      if (utils.isObject(obj[key]) && (!obj[key].constructor || 'Object' == obj[key].constructor.name) && (!obj[key].type || obj[key].type.type)) {
        if (Object.keys(obj[key]).length) {
          // nested object { last: { name: String }}
          this.nested[prefix + key] = true;
          this.add(obj[key], prefix + key + '.');
        } else {
          this.path(prefix + key, obj[key]); // mixed type
        }
      } else {
        this.path(prefix + key, obj[key]);
      }
    }
  };

  ---

  Schema#defaultOptions(options)

  Returns default options for this schema, merged with options.

  Parameters:

  • options <Object>

  Returns:

  • <Object>

  show code

  Schema.prototype.defaultOptions = function (options) {
    if (options && false === options.safe) {
      options.safe = { w: 0 };
    }
    if (options && options.safe && 0 === options.safe.w) {
      // if you turn off safe writes, then versioning goes off as well
      options.versionKey = false;
    }
    options = utils.options({
        strict: true
      , bufferCommands: true
      , capped: false // { size, max, autoIndexId }
      , versionKey: '__v'
      , discriminatorKey: '__t'
      , minimize: true
      , autoIndex: true
      , shardKey: null
      , read: null
      // the following are only applied at construction time
      , noId: false // deprecated, use { _id: false }
      , _id: true
      , noVirtualId: false // deprecated, use { id: false }
      , id: true
  //    , pluralization: true  // only set this to override the global option
    }, options);
    if (options.read) {
      options.read = utils.readPref(options.read);
    }
    return options;
  }

  ---

  Schema#eachPath(fn)

  Iterates the schemas paths similar to Array#forEach.

  Parameters:

  • fn <Function> callback function

  Returns:

  • <Schema> this

  The callback is passed the pathname and schemaType as arguments on each iteration.

  show code

  Schema.prototype.eachPath = function (fn) {
    var keys = Object.keys(this.paths)
      , len = keys.length;
    for (var i = 0; i < len; ++i) {
      fn(keys[i], this.paths[keys[i]]);
    }
    return this;
  };

  ---

  Schema#get(key)

  Gets a schema option.

  Parameters:

  • key <String> option name

  show code

  Schema.prototype.get = function (key) {
    return this.options[key];
  }

  ---

  Schema#index(fields, [options])

  Defines an index (most likely compound) for this schema.

  Parameters:

  • fields <Object>
  • [options] <Object>

  Example

  schema.index({ first: 1, last: -1 })

  show code

  Schema.prototype.index = function (fields, options) {
    options || (options = {});
    if (options.expires)
      utils.expires(options);
    this._indexes.push([fields, options]);
    return this;
  };

  ---

  Schema#indexedPaths()

  Returns indexes from fields and schema-level indexes (cached).

  Returns:

  • <Array>

  show code

  Schema.prototype.indexedPaths = function indexedPaths () {
    if (this._indexedpaths) return this._indexedpaths;
    return this._indexedpaths = this.indexes();
  }

  ---

  Schema#indexes()

  Compiles indexes from fields and schema-level indexes

  show code

  Schema.prototype.indexes = function () {
    'use strict';
    var indexes = [];
    var seenPrefix = {};
    var collectIndexes = function(schema, prefix) {
      if (seenPrefix[prefix]) {
        return;
      }
      seenPrefix[prefix] = true;
      prefix = prefix || '';
      var key, path, index, field, isObject, options, type;
      var keys = Object.keys(schema.paths);
      for (var i = 0; i < keys.length; ++i) {
        key = keys[i];
        path = schema.paths[key];
        if (path instanceof Types.DocumentArray) {
          collectIndexes(path.schema, key + '.');
        } else {
          index = path._index;
          if (false !== index && null != index) {
            field = {};
            isObject = utils.isObject(index);
            options = isObject ? index : {};
            type = 'string' == typeof index ? index :
              isObject ? index.type :
              false;
            if (type && ~Schema.indexTypes.indexOf(type)) {
              field[prefix + key] = type;
            } else {
              field[prefix + key] = 1;
            }
            delete options.type;
            if (!('background' in options)) {
              options.background = true;
            }
            indexes.push([field, options]);
          }
        }
      }
      if (prefix) {
        fixSubIndexPaths(schema, prefix);
      } else {
        schema._indexes.forEach(function (index) {
          if (!('background' in index[1])) index[1].background = true;
        });
        indexes = indexes.concat(schema._indexes);
      }
    };
    collectIndexes(this);
    return indexes;

  ---

  Schema#method(method, [fn])

  Adds an instance method to documents constructed from Models compiled from this schema.

  Parameters:

  • method <String, Object> name
  • [fn] <Function>

  Example

  var schema = kittySchema = new Schema(..);
  schema.method('meow', function () {
    console.log('meeeeeoooooooooooow');
  })
  var Kitty = mongoose.model('Kitty', schema);
  var fizz = new Kitty;
  fizz.meow(); // meeeeeooooooooooooow

  If a hash of name/fn pairs is passed as the only argument, each name/fn pair will be added as methods.

  schema.method({
      purr: function () {}
    , scratch: function () {}
  });
  // later
  fizz.purr();
  fizz.scratch();

  show code

  Schema.prototype.method = function (name, fn) {
    if ('string' != typeof name)
      for (var i in name)
        this.methods[i] = name[i];
    else
      this.methods[name] = fn;
    return this;
  };

  ---

  Schema#path(path, constructor)

  Gets/sets schema paths.

  Parameters:

  • path <String>
  • constructor <Object>

  Sets a path (if arity 2)
  Gets a path (if arity 1)

  Example

  schema.path('name') // returns a SchemaType
  schema.path('name', Number) // changes the schemaType of `name` to Number

  show code

  Schema.prototype.path = function (path, obj) {
    if (obj == undefined) {
      if (this.paths[path]) return this.paths[path];
      if (this.subpaths[path]) return this.subpaths[path];
      // subpaths?
      return /\.\d+\.?.*$/.test(path)
        ? getPositionalPath(this, path)
        : undefined;
    }
    // some path names conflict with document methods
    if (reserved[path]) {
      throw new Error("`" + path + "` may not be used as a schema pathname");
    }
    // update the tree
    var subpaths = path.split(/\./)
      , last = subpaths.pop()
      , branch = this.tree;
    subpaths.forEach(function(sub, i) {
      if (!branch[sub]) branch[sub] = {};
      if ('object' != typeof branch[sub]) {
        var msg = 'Cannot set nested path `' + path + '`. '
                + 'Parent path `'
                + subpaths.slice(0, i).concat([sub]).join('.')
                + '` already set to type ' + branch[sub].name
                + '.';
        throw new Error(msg);
      }
      branch = branch[sub];
    });
    branch[last] = utils.clone(obj);
    this.paths[path] = Schema.interpretAsType(path, obj, this.options);
    return this;
  };

  ---

  Schema#pathType(path)

  Returns the pathType of path for this schema.

  Parameters:

  • path <String>

  Returns:

  • <String>

  Given a path, returns whether it is a real, virtual, nested, or ad-hoc/undefined path.

  show code

  Schema.prototype.pathType = function (path) {
    if (path in this.paths) return 'real';
    if (path in this.virtuals) return 'virtual';
    if (path in this.nested) return 'nested';
    if (path in this.subpaths) return 'real';
    if (/\.\d+\.|\.\d+$/.test(path) && getPositionalPath(this, path)) {
      return 'real';
    } else {
      return 'adhocOrUndefined'
    }
  };

  ---

  Schema#plugin(plugin, opts)

  Registers a plugin for this schema.

  Parameters:

  • plugin <Function> callback
  • opts <Object>

  See:

  • plugins

  show code

  Schema.prototype.plugin = function (fn, opts) {
    fn(this, opts);
    return this;
  };

  ---

  Schema#post(method, fn)

  Defines a post hook for the document

  Parameters:

  • method <String> name of the method to hook
  • fn <Function> callback

  See:

  • hooks.js

  Post hooks fire on the event emitted from document instances of Models compiled from this schema.

  var schema = new Schema(..);
  schema.post('save', function (doc) {
    console.log('this fired after a document was saved');
  });
  var Model = mongoose.model('Model', schema);
  var m = new Model(..);
  m.save(function (err) {
    console.log('this fires after the `post` hook');
  });

  show code

  Schema.prototype.post = function(method, fn){
    return this.queue('on', arguments);
  };

  ---

  Schema#pre(method, callback)

  Defines a pre hook for the document.

  Parameters:

  • method <String>
  • callback <Function>

  See:

  • hooks.js

  Example

  var toySchema = new Schema(..);
  toySchema.pre('save', function (next) {
    if (!this.created) this.created = new Date;
    next();
  })
  toySchema.pre('validate', function (next) {
    if (this.name != 'Woody') this.name = 'Woody';
    next();
  })

  show code

  Schema.prototype.pre = function(){
    return this.queue('pre', arguments);
  };

  ---

  Schema#queue(name, args)

  Adds a method call to the queue.

  Parameters:

  • name <String> name of the document method to call later
  • args <Array> arguments to pass to the method

  show code

  Schema.prototype.queue = function(name, args){
    this.callQueue.push([name, args]);
    return this;
  };

  ---

  Schema#requiredPaths()

  Returns an Array of path strings that are required by this schema.

  Returns:

  • <Array>

  show code

  Schema.prototype.requiredPaths = function requiredPaths () {
    if (this._requiredpaths) return this._requiredpaths;
    var paths = Object.keys(this.paths)
      , i = paths.length
      , ret = [];
    while (i--) {
      var path = paths[i];
      if (this.paths[path].isRequired) ret.push(path);
    }
    return this._requiredpaths = ret;
  }

  ---

  Schema(definition)

  Schema constructor.

  Parameters:

  • definition <Object>

  Inherits:

  • NodeJS EventEmitter

  Events:

  • init: Emitted after the schema is compiled into a Model.

  Example:

  var child = new Schema({ name: String });
  var schema = new Schema({ name: String, age: Number, children: [child] });
  var Tree = mongoose.model('Tree', schema);
  // setting schema options
  new Schema({ name: String }, { _id: false, autoIndex: false })

  Options:

  • autoIndex: bool - defaults to true
  • bufferCommands: bool - defaults to true
  • capped: bool - defaults to false
  • collection: string - no default
  • id: bool - defaults to true
  • _id: bool - defaults to true
  • minimize: bool - controls document#toObject behavior when called manually - defaults to true
  • read: string
  • safe: bool - defaults to true.
  • shardKey: bool - defaults to null
  • strict: bool - defaults to true
  • toJSON - object - no default
  • toObject - object - no default
  • versionKey: bool - defaults to “__v”

  Note:

  When nesting schemas, (children in the example above), always declare the child schema first before passing it into is parent.

  show code

  function Schema (obj, options) {
    if (!(this instanceof Schema))
      return new Schema(obj, options);
    this.paths = {};
    this.subpaths = {};
    this.virtuals = {};
    this.nested = {};
    this.inherits = {};
    this.callQueue = [];
    this._indexes = [];
    this.methods = {};
    this.statics = {};
    this.tree = {};
    this._requiredpaths = undefined;
    this.discriminatorMapping = undefined;
    this._indexedpaths = undefined;
    this.options = this.defaultOptions(options);
    // build paths
    if (obj) {
      this.add(obj);
    }
    // ensure the documents get an auto _id unless disabled
    var auto_id = !this.paths['_id'] && (!this.options.noId && this.options._id);
    if (auto_id) {
      this.add({ _id: {type: Schema.ObjectId, auto: true} });
    }
    // ensure the documents receive an id getter unless disabled
    var autoid = !this.paths['id'] && (!this.options.noVirtualId && this.options.id);
    if (autoid) {
      this.virtual('id').get(idGetter);
    }
  }

  ---

  Schema#set(key, [value])

  Sets/gets a schema option.

  Parameters:

  • key <String> option name
  • [value] <Object> if not passed, the current option value is returned

  show code

  Schema.prototype.set = function (key, value, _tags) {
    if (1 === arguments.length) {
      return this.options[key];
    }
    switch (key) {
      case 'read':
        this.options[key] = utils.readPref(value, _tags)
        break;
      case 'safe':
        this.options[key] = false === value
          ? { w: 0 }
          : value
        break;
      default:
        this.options[key] = value;
    }
    return this;
  }

  ---

  Schema#static(name, fn)

  Adds static “class” methods to Models compiled from this schema.

  Parameters:

  • name <String>
  • fn <Function>

  Example

  var schema = new Schema(..);
  schema.static('findByName', function (name, callback) {
    return this.find({ name: name }, callback);
  });
  var Drink = mongoose.model('Drink', schema);
  Drink.findByName('sanpellegrino', function (err, drinks) {
    //
  });

  If a hash of name/fn pairs is passed as the only argument, each name/fn pair will be added as statics.

  show code

  Schema.prototype.static = function(name, fn) {
    if ('string' != typeof name)
      for (var i in name)
        this.statics[i] = name[i];
    else
      this.statics[name] = fn;
    return this;
  };

  ---

  Schema#virtual(name, [options])

  Creates a virtual type with the given name.

  Parameters:

  • name <String>
  • [options] <Object>

  Returns:

  • <VirtualType>

  show code

  Schema.prototype.virtual = function (name, options) {
    var virtuals = this.virtuals;
    var parts = name.split('.');
    return virtuals[name] = parts.reduce(function (mem, part, i) {
      mem[part] || (mem[part] = (i === parts.length-1)
                              ? new VirtualType(options, name)
                              : {});
      return mem[part];
    }, this.tree);
  };

  ---

  Schema#virtualpath(name)

  Returns the virtual type with the given name.

  Parameters:

  • name <String>

  Returns:

  • <VirtualType>

  show code

  Schema.prototype.virtualpath = function (name) {
    return this.virtuals[name];
  };

  ---

  Schema.indexTypes()

  The allowed index types

  show code

  var indexTypes = '2d 2dsphere hashed text'.split(' ');
  Object.defineProperty(Schema, 'indexTypes', {
      get: function () { return indexTypes }
    , set: function () { throw new Error('Cannot overwrite Schema.indexTypes') }
  })

  ---

  Schema.interpretAsType(path, obj)

  Converts type arguments into Mongoose Types.

  show code

  Schema.interpretAsType = function (path, obj, options) {
    if (obj.constructor && obj.constructor.name != 'Object')
      obj = { type: obj };
    // Get the type making sure to allow keys named "type"
    // and default to mixed if not specified.
    // { type: { type: String, default: 'freshcut' } }
    var type = obj.type && !obj.type.type
      ? obj.type
      : {};
    if ('Object' == type.constructor.name || 'mixed' == type) {
      return new Types.Mixed(path, obj);
    }
    if (Array.isArray(type) || Array == type || 'array' == type) {
      // if it was specified through { type } look for `cast`
      var cast = (Array == type || 'array' == type)
        ? obj.cast
        : type[0];
      if (cast instanceof Schema) {
        return new Types.DocumentArray(path, cast, obj);
      }
      if ('string' == typeof cast) {
        cast = Types[cast.charAt(0).toUpperCase() + cast.substring(1)];
      } else if (cast && (!cast.type || cast.type.type)
                      && 'Object' == cast.constructor.name
                      && Object.keys(cast).length) {
        return new Types.DocumentArray(path, new Schema(cast, options), obj);
      }
      return new Types.Array(path, cast || Types.Mixed, obj);
    }
    var name = 'string' == typeof type
      ? type
      : type.name;
    if (name) {
      name = name.charAt(0).toUpperCase() + name.substring(1);
    }
    if (undefined == Types[name]) {
      throw new TypeError('Undefined type at `' + path +
          '`
    Did you try nesting Schemas? ' +
          'You can only nest using refs or arrays.');
    }
    return new Types[name](path, obj);
  };

  Parameters:

  • path <String>
  • obj <Object> constructor

  ---

  Schema.reserved

  Reserved document keys.

  show code

  Schema.reserved = Object.create(null);
  var reserved = Schema.reserved;
  reserved.on =
  reserved.db =
  reserved.set =
  reserved.get =
  reserved.init =
  reserved.isNew =
  reserved.errors =
  reserved.schema =
  reserved.options =
  reserved.modelName =
  reserved.collection =
  reserved.toObject =
  reserved.emit =    // EventEmitter
  reserved._events = // EventEmitter
  reserved._pres = reserved._posts = 1 // hooks.js

  Keys in this object are names that are rejected in schema declarations b/c they conflict with mongoose functionality. Using these key name will throw an error.

  on, emit, _events, db, get, set, init, isNew, errors, schema, options, modelName, collection, _pres, _posts, toObject

  NOTE: Use of these terms as method names is permitted, but play at your own risk, as they may be existing mongoose document methods you are stomping on.

  var schema = new Schema(..);
   schema.methods.init = function () {} // potentially breaking

  ---

  Schema.Types

  The various built-in Mongoose Schema Types.

  show code

  Schema.Types = require('./schema/index');

  Example:

  var mongoose = require('mongoose');
  var ObjectId = mongoose.Schema.Types.ObjectId;

  Types:

  • String
  • Number
  • Boolean | Bool
  • Array
  • Buffer
  • Date
  • ObjectId | Oid
  • Mixed

  Using this exposed access to the Mixed SchemaType, we can use them in our schema.

  var Mixed = mongoose.Schema.Types.Mixed;
  new mongoose.Schema({ _user: Mixed })

  ---

  Schema#paths

  Schema as flat paths

  Example:

  {
      '_id'        : SchemaType,
    , 'nested.key' : SchemaType,
  }

  show code

  Schema.prototype.paths;

  ---

  Schema#tree

  Schema as a tree

  Example:

  {
      '_id'     : ObjectId
    , 'nested'  : {
          'key' : String
      }
  }

  show code

  Schema.prototype.tree;

  ---

• schemadefault.js

  exports#system.profile

  Default model for querying the system.profiles collection.

  show code

  exports['system.profile'] = new Schema({
      ts: Date
    , info: String // deprecated
    , millis: Number
    , op: String
    , ns: String
    , query: Schema.Types.Mixed
    , updateobj: Schema.Types.Mixed
    , ntoreturn: Number
    , nreturned: Number
    , nscanned: Number
    , responseLength: Number
    , client: String
    , user: String
    , idhack: Boolean
    , scanAndOrder: Boolean
    , keyUpdates: Number
    , cursorid: Number
  }, { noVirtualId: true, noId: true });

  ---

• document.js

  Document#$__buildDoc(obj, [fields], [skipId])

  Builds the default doc structure

  Parameters:

  • obj <Object>
  • [fields] <Object>
  • [skipId] <Boolean>

  Returns:

  • <Object>

  ---

  Document#$__dirty()

  Returns this documents dirty paths / vals.

  ---

  Document#$__doQueue()

  Executes methods queued from the Schema definition

  ---

  Document#$__error(err)

  Registers an error

  Parameters:

  • err <Error>

  ---

  Document#$__fullPath([path])

  Returns the full path to this document.

  Parameters:

  • [path] <String>

  Returns:

  • <String>

  ---

  Document#$__path(path)

  Returns the schematype for the given path.

  Parameters:

  • path <String>

  ---

  Document#$__registerHooks()

  Register default hooks

  ---

  Document#$__reset()

  Resets the internal modified state of this document.

  Returns:

  • <Document>

  ---

  Document#$__set()

  Handles the actual setting of the value and marking the path modified if appropriate.

  ---

  Document#$__setSchema(schema)

  Assigns/compiles schema into this documents prototype.

  Parameters:

  • schema <Schema>

  ---

  Document#$__shouldModify()

  Determine if we should mark this change as modified.

  Returns:

  • <Boolean>

  ---

  Document#$__storeShard()

  Stores the current values of the shard keys.

  Note:

  Shard key values do not / are not allowed to change.

  ---

  Document#$__try(fn, scope)

  Catches errors that occur during execution of fn and stores them to later be passed when save() is executed.

  Parameters:

  • fn <Function> function to execute
  • scope <Object> the scope with which to call fn

  ---

  Document#$toObject()

  Internal helper for toObject() and toJSON() that doesn’t manipulate options

  ---

  Document(obj, [opts], [skipId])

  Document constructor.

  Parameters:

  • obj <Object> the values to set
  • [opts] <Object> optional object containing the fields which were selected in the query returning this document and any populated paths data
  • [skipId] <Boolean> bool, should we auto create an ObjectId _id

  Inherits:

  • NodeJS EventEmitter

  Events:

  • init: Emitted on a document after it has was retreived from the db and fully hydrated by Mongoose.

  • save: Emitted when the document is successfully saved

  show code

  function Document (obj, fields, skipId) {
    this.$__ = new InternalCache;
    this.isNew = true;
    this.errors = undefined;
    var schema = this.schema;
    if ('boolean' === typeof fields) {
      this.$__.strictMode = fields;
      fields = undefined;
    } else {
      this.$__.strictMode = schema.options && schema.options.strict;
      this.$__.selected = fields;
    }
    var required = schema.requiredPaths();
    for (var i = 0; i < required.length; ++i) {
      this.$__.activePaths.require(required[i]);
    }
    setMaxListeners.call(this, 0);
    this._doc = this.$__buildDoc(obj, fields, skipId);
    if (obj) {
      this.set(obj, undefined, true);
    }
    this.$__registerHooks();
  }

  ---

  Document#equals(doc)

  Returns true if the Document stores the same data as doc.

  Parameters:

  • doc <Document> a document to compare

  Returns:

  • <Boolean>

  Documents are considered equal when they have matching _ids, unless neither
  document has an _id, in which case this function falls back to using
  deepEqual().

  show code

  Document.prototype.equals = function (doc) {
    var tid = this.get('_id');
    var docid = doc.get('_id');
    if (!tid && !docid) {
      return deepEqual(this, doc);
    }
    return tid && tid.equals
      ? tid.equals(docid)
      : tid === docid;
  }

  ---

  Document#get(path, [type])

  Returns the value of a path.

  Parameters:

  • path <String>
  • [type] <Schema, String, Number, Buffer, etc..> optionally specify a type for on-the-fly attributes

  Example

  // path
  doc.get('age') // 47
  // dynamic casting to a string
  doc.get('age', String) // "47"

  show code

  Document.prototype.get = function (path, type) {
    var adhocs;
    if (type) {
      adhocs = this.$__.adhocPaths || (this.$__.adhocPaths = {});
      adhocs[path] = Schema.interpretAsType(path, type);
    }
    var schema = this.$__path(path) || this.schema.virtualpath(path)
      , pieces = path.split('.')
      , obj = this._doc;
    for (var i = 0, l = pieces.length; i < l; i++) {
      obj = undefined === obj || null === obj
        ? undefined
        : obj[pieces[i]];
    }
    if (schema) {
      obj = schema.applyGetters(obj, this);
    }
    return obj;
  };

  ---

  Document#getValue(path)

  Gets a raw value from a path (no getters)

  Parameters:

  • path <String>

  show code

  Document.prototype.getValue = function (path) {
    return utils.getValue(path, this._doc);
  }

  ---

  Document#init(doc, fn)

  Initializes the document without setters or marking anything modified.

  Parameters:

  • doc <Object> document returned by mongo
  • fn <Function> callback

  Called internally after a document is returned from mongodb.

  show code

  Document.prototype.init = function (doc, opts, fn) {
    // do not prefix this method with $__ since its
    // used by public hooks
    if ('function' == typeof opts) {
      fn = opts;
      opts = null;
    }
    this.isNew = false;
    // handle docs with populated paths
    if (doc._id && opts && opts.populated && opts.populated.length) {
      var id = String(doc._id);
      for (var i = 0; i < opts.populated.length; ++i) {
        var item = opts.populated[i];
        this.populated(item.path, item._docs[id], item);
      }
    }
    init(this, doc, this._doc);
    this.$__storeShard();
    this.emit('init', this);
    if (fn) fn(null);
    return this;
  };

  ---

  Document#inspect()

  Helper for console.log

  show code

  Document.prototype.inspect = function (options) {
    var opts = options && 'Object' == options.constructor.name ? options :
        this.schema.options.toObject ? clone(this.schema.options.toObject) :
        {};
    opts.minimize = false;
    return inspect(this.toObject(opts));
  };

  ---

  Document#invalidate(path, errorMsg, value)

  Marks a path as invalid, causing validation to fail.

  Parameters:

  • path <String> the field to invalidate
  • errorMsg <String, Error> the error which states the reason `path` was invalid
  • value <Object, String, Number, T> optional invalid value

  The errorMsg argument will become the message of the ValidationError.

  The value argument (if passed) will be available through the ValidationError.value property.

  doc.invalidate('size', 'must be less than 20', 14);
  doc.validate(function (err) {
    console.log(err)
    // prints
    { message: 'Validation failed',
      name: 'ValidationError',
      errors:
       { size:
          { message: 'must be less than 20',
            name: 'ValidatorError',
            path: 'size',
            type: 'user defined',
            value: 14 } } }
  })

  show code

  Document.prototype.invalidate = function (path, err, val) {
    if (!this.$__.validationError) {
      this.$__.validationError = new ValidationError(this);
    }
    if (!err || 'string' === typeof err) {
      err = new ValidatorError(path, err, 'user defined', val)
    }
    if (this.$__.validationError == err) return;
    this.$__.validationError.errors[path] = err;
  }

  ---

  Document#isDirectModified(path)

  Returns true if path was directly set and modified, else false.

  Parameters:

  • path <String>

  Returns:

  • <Boolean>

  Example

  doc.set('documents.0.title', 'changed');
  doc.isDirectModified('documents.0.title') // true
  doc.isDirectModified('documents') // false

  show code

  Document.prototype.isDirectModified = function (path) {
    return (path in this.$__.activePaths.states.modify);
  };

  ---

  Document#isInit(path)

  Checks if path was initialized.

  Parameters:

  • path <String>

  Returns:

  • <Boolean>

  show code

  Document.prototype.isInit = function (path) {
    return (path in this.$__.activePaths.states.init);
  };

  ---

  Document#isModified([path])

  Returns true if this document was modified, else false.

  Parameters:

  • [path] <String> optional

  Returns:

  • <Boolean>

  If path is given, checks if a path or any full path containing path as part of its path chain has been modified.

  Example

  doc.set('documents.0.title', 'changed');
  doc.isModified()                    // true
  doc.isModified('documents')         // true
  doc.isModified('documents.0.title') // true
  doc.isDirectModified('documents')   // false

  show code

  Document.prototype.isModified = function (path) {
    return path
      ? !!~this.modifiedPaths().indexOf(path)
      : this.$__.activePaths.some('modify');
  };

  ---

  Document#isSelected(path)

  Checks if path was selected in the source query which initialized this document.

  Parameters:

  • path <String>

  Returns:

  • <Boolean>

  Example

  Thing.findOne().select('name').exec(function (err, doc) {
     doc.isSelected('name') // true
     doc.isSelected('age')  // false
  })

  show code

  Document.prototype.isSelected = function isSelected (path) {
    if (this.$__.selected) {
      if ('_id' === path) {
        return 0 !== this.$__.selected._id;
      }
      var paths = Object.keys(this.$__.selected)
        , i = paths.length
        , inclusive = false
        , cur
      if (1 === i && '_id' === paths[0]) {
        // only _id was selected.
        return 0 === this.$__.selected._id;
      }
      while (i--) {
        cur = paths[i];
        if ('_id' == cur) continue;
        inclusive = !! this.$__.selected[cur];
        break;
      }
      if (path in this.$__.selected) {
        return inclusive;
      }
      i = paths.length;
      var pathDot = path + '.';
      while (i--) {
        cur = paths[i];
        if ('_id' == cur) continue;
        if (0 === cur.indexOf(pathDot)) {
          return inclusive;
        }
        if (0 === pathDot.indexOf(cur + '.')) {
          return inclusive;
        }
      }
      return ! inclusive;
    }
    return true;
  }

  ---

  Document#markModified(path)

  Marks the path as having pending changes to write to the db.

  Parameters:

  • path <String> the path to mark modified

  Very helpful when using Mixed types.

  Example:

  doc.mixed.type = 'changed';
  doc.markModified('mixed.type');
  doc.save() // changes to mixed.type are now persisted

  show code

  Document.prototype.markModified = function (path) {
    this.$__.activePaths.modify(path);
  }

  ---

  Document#modifiedPaths()

  Returns the list of paths that have been modified.

  Returns:

  • <Array>

  show code

  Document.prototype.modifiedPaths = function () {
    var directModifiedPaths = Object.keys(this.$__.activePaths.states.modify);
    return directModifiedPaths.reduce(function (list, path) {
      var parts = path.split('.');
      return list.concat(parts.reduce(function (chains, part, i) {
        return chains.concat(parts.slice(0, i).concat(part).join('.'));
      }, []));
    }, []);
  };

  ---

  Document#populate([path], [callback])

  Populates document references, executing the callback when complete.

  Parameters:

  • [path] <String, Object> The path to populate or an options object
  • [callback] <Function> When passed, population is invoked

  Returns:

  • <Document> this

  See:

  • Model.populate

  Example:

  doc
  .populate('company')
  .populate({
    path: 'notes',
    match: /airline/,
    select: 'text',
    model: 'modelName'
    options: opts
  }, function (err, user) {
    assert(doc._id == user._id) // the document itself is passed
  })
  // summary
  doc.populate(path)               // not executed
  doc.populate(options);           // not executed
  doc.populate(path, callback)     // executed
  doc.populate(options, callback); // executed
  doc.populate(callback);          // executed

  NOTE:

  Population does not occur unless a callback is passed.
  Passing the same path a second time will overwrite the previous path options.
  See Model.populate() for explaination of options.

  show code

  Document.prototype.populate = function populate () {
    if (0 === arguments.length) return this;
    var pop = this.$__.populate || (this.$__.populate = {});
    var args = utils.args(arguments);
    var fn;
    if ('function' == typeof args[args.length-1]) {
      fn = args.pop();
    }
    // allow `doc.populate(callback)`
    if (args.length) {
      // use hash to remove duplicate paths
      var res = utils.populate.apply(null, args);
      for (var i = 0; i < res.length; ++i) {
        pop[res[i].path] = res[i];
      }
    }
    if (fn) {
      var paths = utils.object.vals(pop);
      this.$__.populate = undefined;
      this.constructor.populate(this, paths, fn);
    }
    return this;
  }

  ---

  Document#populated(path)

  Gets _id(s) used during population of the given path.

  Parameters:

  • path <String>

  Returns:

  • <Array, ObjectId, Number, Buffer, String, undefined>

  Example:

  Model.findOne().populate('author').exec(function (err, doc) {
    console.log(doc.author.name)         // Dr.Seuss
    console.log(doc.populated('author')) // '5144cf8050f071d979c118a7'
  })

  If the path was not populated, undefined is returned.

  show code

  Document.prototype.populated = function (path, val, options) {
    // val and options are internal
    if (null == val) {
      if (!this.$__.populated) return undefined;
      var v = this.$__.populated[path];
      if (v) return v.value;
      return undefined;
    }
    // internal
    if (true === val) {
      if (!this.$__.populated) return undefined;
      return this.$__.populated[path];
    }
    this.$__.populated || (this.$__.populated = {});
    this.$__.populated[path] = { value: val, options: options };
    return val;
  }

  ---

  Document#set(path, val, [type], [options])

  Sets the value of a path, or many paths.

  Parameters:

  • path <String, Object> path or object of key/vals to set
  • val <Any> the value to set
  • [type] <Schema, String, Number, Buffer, etc..> optionally specify a type for “on-the-fly” attributes
  • [options] <Object> optionally specify options that modify the behavior of the set

  Example:

  // path, value
  doc.set(path, value)
  // object
  doc.set({
      path  : value
    , path2 : {
         path  : value
      }
  })
  // only-the-fly cast to number
  doc.set(path, value, Number)
  // only-the-fly cast to string
  doc.set(path, value, String)
  // changing strict mode behavior
  doc.set(path, value, { strict: false });

  show code

  ``` Document.prototype.set = function (path, val, type, options) { if (type && ‘Object’ == type.constructor.name) {

  options = type;
  type = undefined;

  }

  var merge = options && options.merge

  , adhoc = type && true !== type
  , constructing = true === type
  , adhocs

  var strict = options && ‘strict’ in options

  ? options.strict
  : this.$__.strictMode;

  if (adhoc) {

  adhocs = this.$__.adhocPaths || (this.$__.adhocPaths = {});
  adhocs[path] = Schema.interpretAsType(path, type);

  }

  if (‘string’ !== typeof path) {

  // new Document({ key: val })
  if (null === path || undefined === path) {
    var _ = path;
    path = val;
    val = _;
  } else {
    var prefix = val
      ? val + '.'
      : '';
    if (path instanceof Document) path = path._doc;
    var keys = Object.keys(path)
      , i = keys.length
      , pathtype
      , key