private

  • index.js

    Mongoose#_applyPlugins(schema)

    Applies global plugins to schema.

    Parameters:

    show code

    1. Mongoose.prototype._applyPlugins = function(schema) {
    2.   if (schema.$globalPluginsApplied) {
    3.     return;
    4.   }
    5.   var i;
    6.   var len;
    7.   for (i = 0, len = this.plugins.length; i < len; ++i) {
    8.     schema.plugin(this.plugins[i][0], this.plugins[i][1]);
    9.   }
    10.   schema.$globalPluginsApplied = true;
    11.   for (i = 0, len = schema.childSchemas.length; i < len; ++i) {
    12.     this._applyPlugins(schema.childSchemas[i].schema);
    13.   }
    14. };
    15. Mongoose.prototype._applyPlugins.$hasSideEffects = true;

    Mongoose#Aggregate()

    The Mongoose Aggregate constructor

    Mongoose#CastError(type, value, path, [reason])

    The Mongoose CastError constructor

    Parameters:

    • type <String> The name of the type
    • value <Any> The value that failed to cast
    • path <String> The path a.b.c in the doc where this cast error occurred
    • [reason] <Error> The original error that was thrown

    MongooseThenable#catch(onFulfilled, onRejected)

    Ability to use mongoose object as a pseudo-promise so .connect().then()
    and .disconnect().then() are viable.

    Parameters:

    Returns:

    show code

    1. MongooseThenable.prototype.catch = function(onRejected) {
    2.   return this.then(null, onRejected);
    3. };

    checkReplicaSetInUri(uri)

    Checks if ?replicaSet query parameter is specified in URI

    Parameters:

    Returns:

    Example:

    1. checkReplicaSetInUri('localhost:27000?replicaSet=rs0'); // true

    show code

    1. var checkReplicaSetInUri = function(uri) {
    2.   if (!uri) {
    3.     return false;
    4.   }
    6.   var queryStringStart = uri.indexOf('?');
    7.   var isReplicaSet = false;
    8.   if (queryStringStart !== -1) {
    9.     try {
    10.       var obj = querystring.parse(uri.substr(queryStringStart + 1));
    11.       if (obj && obj.replicaSet) {
    12.         isReplicaSet = true;
    13.       }
    14.     } catch (e) {
    15.       return false;
    16.     }
    17.   }
    19.   return isReplicaSet;
    20. };

    Mongoose#Collection()

    The Mongoose Collection constructor

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

    Opens the default mongoose connection.

    Parameters:

    • uri(s) <String>
    • [options] <Object>
    • [options.useMongoClient] <Boolean> false by default, set to true to use new mongoose connection logic
    • [callback] <Function>

    Returns:

    See:

    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:

    1. mongoose.connect('mongodb://user:pass@localhost:port/database');
    3. // replica sets
    4. var uri = 'mongodb://user:pass@localhost:port,anotherhost:port,yetanother:port/mydatabase';
    5. mongoose.connect(uri);
    7. // with options
    8. mongoose.connect(uri, options);
    10. // connecting to multiple mongos
    11. var uri = 'mongodb://hostA:27501,hostB:27501';
    12. var opts = { mongos: true };
    13. mongoose.connect(uri, opts);
    15. // optional callback that gets fired when initial connection completed
    16. var uri = 'mongodb://nonexistent.domain:27000';
    17. mongoose.connect(uri, function(error) {
    18.   // if error is truthy, the initial connection failed.
    19. })

    show code

    1. Mongoose.prototype.connect = function() {
    2.   var conn = this.connection;
    3.   if ((arguments.length === 2 || arguments.length === 3) &&
    4.       typeof arguments[0] === 'string' &&
    5.       typeof arguments[1] === 'object' &&
    6.       arguments[1].useMongoClient === true) {
    7.     return conn.openUri(arguments[0], arguments[1], arguments[2]);
    8.   }
    9.   if (rgxReplSet.test(arguments[0]) || checkReplicaSetInUri(arguments[0])) {
    10.     return new MongooseThenable(this, conn.openSet.apply(conn, arguments));
    11.   }
    13.   return new MongooseThenable(this, conn.open.apply(conn, arguments));
    14. };
    15. Mongoose.prototype.connect.$hasSideEffects = true;

    Mongoose#Connection()

    The Mongoose Connection constructor

    Mongoose#createConnection([uri], [options], [options.config], [options.config.autoIndex], [options.useMongoClient])

    Creates a Connection instance.

    Parameters:

    • [uri] <String> a mongodb:// URI
    • [options] <Object> options to pass to the driver
    • [options.config] <Object> mongoose-specific options
    • [options.config.autoIndex] <Boolean> set to false to disable automatic index creation for all models associated with this connection.
    • [options.useMongoClient] <Boolean> false by default, set to true to use new mongoose connection logic

    Returns:

    • <Connection, Promise> the created Connection object, or promise that resolves to the connection if `useMongoClient` option specified.

    See:

    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:

    1. // with mongodb:// URI
    2. db = mongoose.createConnection('mongodb://user:pass@localhost:port/database');
    4. // and options
    5. var opts = { db: { native_parser: true }}
    6. db = mongoose.createConnection('mongodb://user:pass@localhost:port/database', opts);
    8. // replica sets
    9. db = mongoose.createConnection('mongodb://user:pass@localhost:port,anotherhost:port,yetanother:port/database');
    11. // and options
    12. var opts = { replset: { strategy: 'ping', rs_name: 'testSet' }}
    13. db = mongoose.createConnection('mongodb://user:pass@localhost:port,anotherhost:port,yetanother:port/database', opts);
    15. // with [host, database_name[, port] signature
    16. db = mongoose.createConnection('localhost', 'database', port)
    18. // and options
    19. var opts = { server: { auto_reconnect: false }, user: 'username', pass: 'mypassword' }
    20. db = mongoose.createConnection('localhost', 'database', port, opts)
    22. // initialize now, connect later
    23. db = mongoose.createConnection();
    24. db.open('localhost', 'database', port, [opts]);

    show code

    1. Mongoose.prototype.createConnection = function(uri, options, callback) {
    2.   var conn = new Connection(this);
    3.   this.connections.push(conn);
    5.   var rsOption = options && (options.replset || options.replSet);
    7.   if (options && options.useMongoClient) {
    8.     return conn.openUri(uri, options, callback);
    9.   }
    11.   if (arguments.length) {
    12.     if (rgxReplSet.test(arguments[0]) || checkReplicaSetInUri(arguments[0])) {
    13.       conn._openSetWithoutPromise.apply(conn, arguments);
    14.     } else if (rsOption &&
    15.         (rsOption.replicaSet || rsOption.rs_name)) {
    16.       conn._openSetWithoutPromise.apply(conn, arguments);
    17.     } else {
    18.       conn._openWithoutPromise.apply(conn, arguments);
    19.     }
    20.   }
    22.   return conn;
    23. };
    24. Mongoose.prototype.createConnection.$hasSideEffects = true;

    Mongoose#disconnect([fn])

    Disconnects all connections.

    Parameters:

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

    Returns:

    show code

    1. Mongoose.prototype.disconnect = function(fn) {
    2.   var _this = this;
    4.   var Promise = PromiseProvider.get();
    5.   return new MongooseThenable(this, new Promise.ES6(function(resolve, reject) {
    6.     var remaining = _this.connections.length;
    7.     if (remaining <= 0) {
    8.       fn && fn();
    9.       resolve();
    10.       return;
    11.     }
    12.     _this.connections.forEach(function(conn) {
    13.       conn.close(function(error) {
    14.         if (error) {
    15.           fn && fn(error);
    16.           reject(error);
    17.           return;
    18.         }
    19.         if (!--remaining) {
    20.           fn && fn();
    21.           resolve();
    22.         }
    23.       });
    24.     });
    25.   }));
    26. };
    27. Mongoose.prototype.disconnect.$hasSideEffects = true;

    Mongoose#Document()

    The Mongoose Document constructor.

    Mongoose#DocumentProvider()

    The Mongoose DocumentProvider constructor.

    Mongoose#Error()

    The MongooseError constructor.

    Mongoose#get(key)

    Gets mongoose options

    Parameters:

    Example:

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

    Mongoose#getPromiseConstructor()

    Returns the current ES6-style promise constructor. In Mongoose 4.x,
    equivalent to mongoose.Promise.ES6, but will change once we get rid
    of the .ES6 bit.

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

    Defines a model or retrieves it.

    Parameters:

    • name <String, Function> model name or class extending Model
    • [schema] <Schema>
    • [collection] <String> name (optional, inferred 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:

    1. var mongoose = require('mongoose');
    3. // define an Actor model with this mongoose instance
    4. mongoose.model('Actor', new Schema({ name: String }));
    6. // create a new connection
    7. var conn = mongoose.createConnection(..);
    9. // retrieve the Actor model
    10. 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:

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

    show code

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

    1. model = name;
    2. name = model.name;
    3. if (!(model.prototype instanceof Model)) {
    4.   throw new mongoose.Error('The provided class ' + name + ' must extend Model');
    5. }

    }

    if (typeof schema === ‘string’) {

    1. collection = schema;
    2. schema = false;

    }

    if (utils.isObject(schema) && !(schema.instanceOfSchema)) {

    1. schema = new Schema(schema);

    } if (schema && !schema.instanceOfSchema) {

    1. throw new Error('The 2nd parameter to `mongoose.model()` should be a ' +
    2.   'schema or a POJO');

    }

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

    1. skipInit = collection;
    2. collection = null;

    }

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

    1. options = skipInit;
    2. skipInit = true;

    } else {

    1. options = {};

    }

    // look up schema for the collection. if (!this.modelSchemas[name]) {

    1. if (schema) {
    2.   // cache it so we only apply plugins once
    3.   this.modelSchemas[name] = schema;
    4. } else {
    5.   throw new mongoose.Error.MissingSchemaError(name);
    6. }

    }

    if (schema) {

    1. this._applyPlugins(schema);

    }

    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] && options.cache !== false) {

    1. if (schema && schema.instanceOfSchema && schema !== this.models[name].schema) {
    2.   throw new mongoose.Error.OverwriteModelError(name);
    3. }
    5. if (collection) {
    6.   // subclass current model with alternate collection
    7.   model = this.models[name];
    8.   schema = model.prototype.schema;
    9.   sub = model.__subclass(this.connection, schema, collection);
    10.   // do not cache the sub model
    11.   return sub;
    12. }
    14. return this.models[name];

    }

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

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

    }

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

  1.   if (!collection) {
  2.     collection = schema.get('collection') || format(name, schema.options);
  3.   }
  5.   var connection = options.connection || this.connection;
  6.   model = this.Model.compile(model || name, schema, collection, connection, this);
  8.   if (!skipInit) {
  9.     model.init();
  10.   }
  12.   if (options.cache === false) {
  13.     return model;
  14.   }
  16.   this.models[name] = model;
  17.   return this.models[name];
  18. };
  19. Mongoose.prototype.model.$hasSideEffects = true;
  20. ```
  22. ---
  24. ### [Mongoose#Model()](#index_Mongoose-Model)
  26. The Mongoose [Model](#model_Model) constructor.
  28. ---
  30. ### [Mongoose#modelNames()](#index_Mongoose-modelNames)
  32. Returns an array of model names created on this instance of Mongoose.
  34. #### Returns:
  36. -   &lt;[Array](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array)&gt;
  38. #### Note:
  40. *Does not include names of models created using `connection.model()`.*
  42. show code
  44. ```
  45. Mongoose.prototype.modelNames = function() {
  46.   var names = Object.keys(this.models);
  47.   return names;
  48. };
  49. Mongoose.prototype.modelNames.$hasSideEffects = true;
  50. ```
  52. ---
  54. ### [Mongoose()](#index_Mongoose)
  56. Mongoose constructor.
  58. The exports object of the `mongoose` module is an instance of this class.  
  59. Most apps will only use this one instance.
  61. show code
  63. ```
  64. function Mongoose() {
  65.   this.connections = [];
  66.   this.models = {};
  67.   this.modelSchemas = {};
  68.   // default global options
  69.   this.options = {
  70.     pluralization: true
  71.   };
  72.   var conn = this.createConnection(); // default connection
  73.   conn.models = this.models;
  75.   Object.defineProperty(this, 'plugins', {
  76.     configurable: false,
  77.     enumerable: true,
  78.     writable: false,
  79.     value: [
  80.       [saveSubdocs, { deduplicate: true }],
  81.       [validateBeforeSave, { deduplicate: true }],
  82.       [shardingPlugin, { deduplicate: true }]
  83.     ]
  84.   });
  85. }
  86. ```
  88. ---
  90. ### [Mongoose#Mongoose()](#index_Mongoose-Mongoose)
  92. The Mongoose constructor
  94. The exports of the mongoose module is an instance of this class.
  96. #### Example:
  98. ```
  99. var mongoose = require('mongoose');
  100. var mongoose2 = new mongoose.Mongoose();
  101. ```
  103. ---
  105. ### [MongooseThenable()](#index_MongooseThenable)
  107. Wraps the given Mongoose instance into a thenable (pseudo-promise). This  
  108. is so `connect()` and `disconnect()` can return a thenable while maintaining  
  109. backwards compatibility.
  111. show code
  113. ```
  114. function MongooseThenable(mongoose, promise) {
  115.   var _this = this;
  116.   for (var key in mongoose) {
  117.     if (typeof mongoose[key] === 'function' && mongoose[key].$hasSideEffects) {
  118.       (function(key) {
  119.         _this[key] = function() {
  120.           return mongoose[key].apply(mongoose, arguments);
  121.         };
  122.       })(key);
  123.     } else if (['connection', 'connections'].indexOf(key) !== -1) {
  124.       _this[key] = mongoose[key];
  125.     }
  126.   }
  127.   this.$opPromise = promise;
  128. }
  130. MongooseThenable.prototype = new Mongoose;
  131. ```
  133. ---
  135. ### [Mongoose#plugin(`fn`, `[opts]`)](#index_Mongoose-plugin)
  137. Declares a global plugin executed on all Schemas.
  139. #### Parameters:
  141. -   `fn` &lt;[Function](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Function)&gt; plugin callback
  142. -   `[opts]` &lt;[Object](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object)&gt; optional options
  144. #### Returns:
  146. -   &lt;[Mongoose](#index_Mongoose)&gt; this
  148. #### See:
  150. -   [plugins]($eb672f4e0179b36b.md "plugins")
  152. Equivalent to calling `.plugin(fn)` on each Schema you create.
  154. show code
  156. ```
  157. Mongoose.prototype.plugin = function(fn, opts) {
  158.   this.plugins.push([fn, opts]);
  159.   return this;
  160. };
  161. Mongoose.prototype.plugin.$hasSideEffects = true;
  162. ```
  164. ---
  166. ### [function Object() { \[native code\] }#Promise()](#index_function%20Object()%20%7B%20%5Bnative%20code%5D%20%7D-Promise)
  168. The Mongoose [Promise](#promise_Promise) constructor.
  170. ---
  172. ### [Mongoose#PromiseProvider()](#index_Mongoose-PromiseProvider)
  174. Storage layer for mongoose promises
  176. ---
  178. ### [Mongoose#Query()](#index_Mongoose-Query)
  180. The Mongoose [Query](#query_Query) constructor.
  182. ---
  184. ### [Mongoose#Schema()](#index_Mongoose-Schema)
  186. The Mongoose [Schema](#schema_Schema) constructor
  188. #### Example:
  190. ```
  191. var mongoose = require('mongoose');
  192. var Schema = mongoose.Schema;
  193. var CatSchema = new Schema(..);
  194. ```
  196. ---
  198. ### [Mongoose#SchemaType()](#index_Mongoose-SchemaType)
  200. The Mongoose [SchemaType](#schematype_SchemaType) constructor
  202. ---
  204. ### [Mongoose#set(`key`, `value`)](#index_Mongoose-set)
  206. Sets mongoose options
  208. #### Parameters:
  210. -   `key` &lt;[String](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String)&gt;
  211. -   `value` &lt;[String](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String), [Function](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Function), [Boolean](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Boolean)&gt;
  213. #### Example:
  215. ```
  216. mongoose.set('test', value) // sets the 'test' option to `value`
  218. mongoose.set('debug', true) // enable logging collection methods + arguments to the console
  220. mongoose.set('debug', function(collectionName, methodName, arg1, arg2...) {}); // use custom function to log collection methods + arguments
  221. ```
  223. show code
  225. ```
  226. Mongoose.prototype.set = function(key, value) {
  227.   if (arguments.length === 1) {
  228.     return this.options[key];
  229.   }
  231.   this.options[key] = value;
  232.   return this;
  233. };
  234. Mongoose.prototype.set.$hasSideEffects = true;
  235. ```
  237. ---
  239. ### [()](#index_)
  241. Expose connection states for user-land
  243. show code
  245. ```
  246. Mongoose.prototype.STATES = STATES;
  247. ```
  249. ---
  251. ### [MongooseThenable#then(`onFulfilled`, `onRejected`)](#index_MongooseThenable-then)
  253. Ability to use mongoose object as a pseudo-promise so `.connect().then()`  
  254. and `.disconnect().then()` are viable.
  256. #### Parameters:
  258. -   `onFulfilled` &lt;[Function](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Function)&gt;
  259. -   `onRejected` &lt;[Function](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Function)&gt;
  261. #### Returns:
  263. -   &lt;[Promise](#promise_Promise)&gt;
  265. show code
  267. ```
  268. MongooseThenable.prototype.then = function(onFulfilled, onRejected) {
  269.   var Promise = PromiseProvider.get();
  270.   if (!this.$opPromise) {
  271.     return new Promise.ES6(function(resolve, reject) {
  272.       reject(new Error('Can only call `.then()` if connect() or disconnect() ' +
  273.         'has been called'));
  274.     }).then(onFulfilled, onRejected);
  275.   }
  276.   this.$opPromise.$hasHandler = true;
  277.   return this.$opPromise.then(onFulfilled, onRejected);
  278. };
  279. ```
  281. ---
  283. ### [Mongoose#VirtualType()](#index_Mongoose-VirtualType)
  285. The Mongoose [VirtualType](#virtualtype_VirtualType) constructor
  287. ---
  289. ### [Mongoose#connection](#index_Mongoose-connection)
  291. The default connection of the mongoose module.
  293. #### Example:
  295. ```
  296. var mongoose = require('mongoose');
  297. mongoose.connect(...);
  298. mongoose.connection.on('error', cb);
  299. ```
  301. This is the connection used by default for every model created using [mongoose.model](#index_Mongoose-model).
  303. show code
  305. ```
  306. Mongoose.prototype.__defineGetter__('connection', function() {
  307.   return this.connections[0];
  308. });
  310. Mongoose.prototype.__defineSetter__('connection', function(v) {
  311.   if (v instanceof Connection) {
  312.     this.connections[0] = v;
  313.     this.models = v.models;
  314.   }
  315. });
  316. ```
  318. #### Returns:
  320. -   &lt;[Connection](#connection_Connection)&gt;
  322. ---
  324. ### [Mongoose#mongo](#index_Mongoose-mongo)
  326. The [node-mongodb-native](https://github.com/mongodb/node-mongodb-native) driver Mongoose uses.
  328. show code
  330. ```
  331. Mongoose.prototype.mongo = require('mongodb');
  332. ```
  334. ---
  336. ### [Mongoose#mquery](#index_Mongoose-mquery)
  338. The [mquery](https://github.com/aheckmann/mquery) query builder Mongoose uses.
  340. show code
  342. ```
  343. Mongoose.prototype.mquery = require('mquery');
  344. ```
  346. ---
  348. ### [Mongoose#SchemaTypes](#index_Mongoose-SchemaTypes)
  350. The various Mongoose SchemaTypes.
  352. #### Note:
  354. *Alias of mongoose.Schema.Types for backwards compatibility.*
  356. show code
  358. ```
  359. Mongoose.prototype.SchemaTypes = Schema.Types;
  360. ```
  362. #### See:
  364. -   [Schema.SchemaTypes](#schema_Schema.Types "Schema.SchemaTypes")
  366. ---
  368. ### [Mongoose#Types](#index_Mongoose-Types)
  370. The various Mongoose Types.
  372. #### Example:
  374. ```
  375. var mongoose = require('mongoose');
  376. var array = mongoose.Types.Array;
  377. ```
  379. #### Types:
  381. -   [ObjectId](#types-objectid-js)
  382. -   [Buffer](#types-buffer-js)
  383. -   [SubDocument](#types-embedded-js)
  384. -   [Array](#types-array-js)
  385. -   [DocumentArray](#types-documentarray-js)
  387. Using this exposed access to the `ObjectId` type, we can construct ids on demand.
  389. ```
  390. var ObjectId = mongoose.Types.ObjectId;
  391. var id1 = new ObjectId;
  392. ```
  394. show code
  396. ```
  397. Mongoose.prototype.Types = Types;
  398. ```
  400. ---
  402. ### [Mongoose#version](#index_Mongoose-version)
  404. The Mongoose version
  406. show code
  408. ```
  409. Mongoose.prototype.version = pkg.version;
  410. ```
  412. ---

  • virtualtype.js

    VirtualType#applyGetters(value, scope)

    Applies getters to value using optional scope.

    Parameters:

    Returns:

    • <T> the value after applying all getters

    show code

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

    VirtualType#applySetters(value, scope)

    Applies setters to value using optional scope.

    Parameters:

    Returns:

    • <T> the value after applying all setters

    show code

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

    VirtualType#get(fn)

    Defines a getter.

    Parameters:

    Returns:

    Example:

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

    show code

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

    VirtualType#set(fn)

    Defines a setter.

    Parameters:

    Returns:

    Example:

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

    show code

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

    VirtualType()

    VirtualType constructor

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

    Example:

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

    show code

    1. function VirtualType(options, name) {
    2.   this.path = name;
    3.   this.getters = [];
    4.   this.setters = [];
    5.   this.options = options || {};
    6. }

  • browserDocument.js

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

    Document constructor.

    Parameters:

    • obj <Object> the values to set
    • [fields] <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:

    Events:

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

    • save: Emitted when the document is successfully saved

    show code

    ``` function Document(obj, schema, fields, skipId, skipInit) { if (!(this instanceof Document)) {

    1. return new Document(obj, schema, fields, skipId, skipInit);

    }

  1.   if (utils.isObject(schema) && !schema.instanceOfSchema) {
  2.     schema = new Schema(schema);
  3.   }
  5.   // When creating EmbeddedDocument, it already has the schema and he doesn't need the _id
  6.   schema = this.schema || schema;
  8.   // Generate ObjectId if it is missing, but it requires a scheme
  9.   if (!this.schema && schema.options._id) {
  10.     obj = obj || {};
  12.     if (obj._id === undefined) {
  13.       obj._id = new ObjectId();
  14.     }
  15.   }
  17.   if (!schema) {
  18.     throw new MongooseError.MissingSchemaError();
  19.   }
  21.   this.$__setSchema(schema);
  23.   this.$__ = new InternalCache;
  24.   this.$__.emitter = new EventEmitter();
  25.   this.isNew = true;
  26.   this.errors = undefined;
  28.   if (typeof fields === 'boolean') {
  29.     this.$__.strictMode = fields;
  30.     fields = undefined;
  31.   } else {
  32.     this.$__.strictMode = this.schema.options && this.schema.options.strict;
  33.     this.$__.selected = fields;
  34.   }
  36.   var required = this.schema.requiredPaths();
  37.   for (var i = 0; i < required.length; ++i) {
  38.     this.$__.activePaths.require(required[i]);
  39.   }
  41.   this.$__.emitter.setMaxListeners(0);
  42.   this._doc = this.$__buildDoc(obj, fields, skipId);
  44.   if (!skipInit && obj) {
  45.     this.init(obj);
  46.   }
  48.   this.$__registerHooksFromSchema();
  50.   // apply methods
  51.   for (var m in schema.methods) {
  52.     this[m] = schema.methods[m];
  53.   }
  54.   // apply statics
  55.   for (var s in schema.statics) {
  56.     this[s] = schema.statics[s];
  57.   }
  58. }
  59. ```
  61. ---

  • types/documentarray.js

    MongooseDocumentArray(values, path, doc)

    DocumentArray constructor

    Parameters:

    Returns:

    Inherits:

    See:

    show code

    1. function MongooseDocumentArray(values, path, doc) {
    2.   var arr = [].concat(values);
    3.   arr._path = path;
    5.   var props = {
    6.     isMongooseArray: true,
    7.     isMongooseDocumentArray: true,
    8.     validators: [],
    9.     _atomics: {},
    10.     _schema: void 0,
    11.     _handlers: void 0
    12.   };
    14.   // Values always have to be passed to the constructor to initialize, since
    15.   // otherwise MongooseArray#push will mark the array as modified to the parent.
    16.   var keysMA = Object.keys(MongooseArray.mixin);
    17.   var numKeys = keysMA.length;
    18.   for (var j = 0; j < numKeys; ++j) {
    19.     arr[keysMA[j]] = MongooseArray.mixin[keysMA[j]];
    20.   }
    22.   var keysMDA = Object.keys(MongooseDocumentArray.mixin);
    23.   numKeys = keysMDA.length;
    24.   for (var i = 0; i < numKeys; ++i) {
    25.     arr[keysMDA[i]] = MongooseDocumentArray.mixin[keysMDA[i]];
    26.   }
    28.   var keysP = Object.keys(props);
    29.   numKeys = keysP.length;
    30.   for (var k = 0; k < numKeys; ++k) {
    31.     arr[keysP[k]] = props[keysP[k]];
    32.   }
    34.   // Because doc comes from the context of another function, doc === global
    35.   // can happen if there was a null somewhere up the chain (see #3020 && #3034)
    36.   // RB Jun 17, 2015 updated to check for presence of expected paths instead
    37.   // to make more proof against unusual node environments
    38.   if (doc && doc instanceof Document) {
    39.     arr._parent = doc;
    40.     arr._schema = doc.schema.path(path);
    41.     arr._handlers = {
    42.       isNew: arr.notify('isNew'),
    43.       save: arr.notify('save')
    44.     };
    46.     doc.on('save', arr._handlers.save);
    47.     doc.on('isNew', arr._handlers.isNew);
    48.   }
    50.   return arr;
    51. }

    MongooseDocumentArray._cast()

    Overrides MongooseArray#cast

    MongooseDocumentArray.id(id)

    Searches array items for the first document with a matching _id.

    Parameters:

    Returns:

    Example:

    1. var embeddedDoc = m.array.id(some_id);

    MongooseDocumentArray.toObject([options])

    Returns a native js Array of plain js objects

    Parameters:

    • [options] <Object> optional options to pass to each documents <code>toObject</code> method call during conversion

    Returns:

    NOTE:

    Each sub-document is converted to a plain object by calling its #toObject method.

    MongooseDocumentArray.inspect()

    Helper for console.log

    MongooseDocumentArray.create(obj)

    Creates a subdocument casted to this schema.

    Parameters:

    • obj <Object> the value to cast to this arrays SubDocument schema

    This is the same subdocument constructor used for casting.

    MongooseDocumentArray.notify(event)

    Creates a fn that notifies all child docs of event.

    Parameters:

    Returns:

  • types/array.js

    MongooseArray#$__getAtomics()

    Depopulates stored atomic operation values as necessary for direct insertion to MongoDB.

    Returns:

    If no atomics exist, we return all array values after conversion.

    MongooseArray#$shift()

    Atomically shifts the array at most one time per document save().

    See:

    NOTE:

    Calling this mulitple times on an array before saving sends the same command as calling it once.
    This update is implemented using the MongoDB $pop method which enforces this restriction.

    1. doc.array = [1,2,3];
    3.  var shifted = doc.array.$shift();
    4.  console.log(shifted); // 1
    5.  console.log(doc.array); // [2,3]
    7.  // no affect
    8.  shifted = doc.array.$shift();
    9.  console.log(doc.array); // [2,3]
    11.  doc.save(function (err) {
    12.    if (err) return handleError(err);
    14.    // we saved, now $shift works again
    15.    shifted = doc.array.$shift();
    16.    console.log(shifted ); // 2
    17.    console.log(doc.array); // [3]
    18.  })

    MongooseArray(values, path, doc)

    Mongoose Array constructor.

    Parameters:

    Inherits:

    See:

    NOTE:

    Values always have to be passed to the constructor to initialize, otherwise MongooseArray#push will mark the array as modified.

    show code

    1. function MongooseArray(values, path, doc) {
    2.   var arr = [].concat(values);
    4.   var keysMA = Object.keys(MongooseArray.mixin);
    5.   var numKeys = keysMA.length;
    6.   for (var i = 0; i < numKeys; ++i) {
    7.     arr[keysMA[i]] = MongooseArray.mixin[keysMA[i]];
    8.   }
    10.   arr._path = path;
    11.   arr.isMongooseArray = true;
    12.   arr.validators = [];
    13.   arr._atomics = {};
    14.   arr._schema = void 0;
    16.   // Because doc comes from the context of another function, doc === global
    17.   // can happen if there was a null somewhere up the chain (see #3020)
    18.   // RB Jun 17, 2015 updated to check for presence of expected paths instead
    19.   // to make more proof against unusual node environments
    20.   if (doc && doc instanceof Document) {
    21.     arr._parent = doc;
    22.     arr._schema = doc.schema.path(path);
    23.   }
    25.   return arr;
    26. }
    28. MongooseArray.mixin = {

    MongooseArray#remove()

    Alias of pull

    See:

    MongooseArray._cast(value)

    Casts a member based on this arrays schema.

    Parameters:

    • value <T>

    Returns:

    • <value> the casted value

    MongooseArray._mapCast()

    Internal helper for .map()

    Returns:

    MongooseArray._markModified(embeddedDoc, embeddedPath)

    Marks this array as modified.

    Parameters:

    • embeddedDoc <EmbeddedDocument> the embedded doc that invoked this method on the Array
    • embeddedPath <String> the path which changed in the embeddedDoc

    If it bubbles up from an embedded document change, then it takes the following arguments (otherwise, takes 0 arguments)

    MongooseArray._registerAtomic(op, val)

    Register an atomic operation with the parent.

    Parameters:

    • op <Array> operation
    • val <T>

    MongooseArray.$pop()

    Pops the array atomically at most one time per document save().

    See:

    NOTE:

    Calling this mulitple times on an array before saving sends the same command as calling it once.
    This update is implemented using the MongoDB $pop method which enforces this restriction.

    1. doc.array = [1,2,3];
    3.  var popped = doc.array.$pop();
    4.  console.log(popped); // 3
    5.  console.log(doc.array); // [1,2]
    7.  // no affect
    8.  popped = doc.array.$pop();
    9.  console.log(doc.array); // [1,2]
    11.  doc.save(function (err) {
    12.    if (err) return handleError(err);
    14.    // we saved, now $pop works again
    15.    popped = doc.array.$pop();
    16.    console.log(popped); // 2
    17.    console.log(doc.array); // [1]
    18.  })

    MongooseArray.addToSet([args...])

    Adds values to the array if not already present.

    Parameters:

    • [args...] <T>

    Returns:

    • <Array> the values that were added

    Example:

    1. console.log(doc.array) // [2,3,4]
    2. var added = doc.array.addToSet(4,5);
    3. console.log(doc.array) // [2,3,4,5]
    4. console.log(added)     // [5]

    MongooseArray.hasAtomics()

    Returns the number of pending atomic operations to send to the db for this array.

    Returns:

    MongooseArray.indexOf(obj)

    Return the index of obj or -1 if not found.

    Parameters:

    • obj <Object> the item to look for

    Returns:

    MongooseArray.inspect()

    Helper for console.log

    MongooseArray.nonAtomicPush([args...])

    Pushes items to the array non-atomically.

    Parameters:

    • [args...] <T>

    NOTE:

    marks the entire array as modified, which if saved, will store it as a $set operation, potentially overwritting any changes that happen between when you retrieved the object and when you save it.

    MongooseArray.pop()

    Wraps Array#pop with proper change tracking.

    See:

    Note:

    marks the entire array as modified which will pass the entire thing to $set potentially overwritting any changes that happen between when you retrieved the object and when you save it.

    MongooseArray.pull([args...])

    Pulls items from the array atomically. Equality is determined by casting
    the provided value to an embedded document and comparing using
    the Document.equals() function.

    Parameters:

    • [args...] <T>

    See:

    Examples:

    1. doc.array.pull(ObjectId)
    2. doc.array.pull({ _id: 'someId' })
    3. doc.array.pull(36)
    4. doc.array.pull('tag 1', 'tag 2')

    To remove a document from a subdocument array we may pass an object with a matching _id.

    1. doc.subdocs.push({ _id: 4815162342 })
    2. doc.subdocs.pull({ _id: 4815162342 }) // removed

    Or we may passing the _id directly and let mongoose take care of it.

    1. doc.subdocs.push({ _id: 4815162342 })
    2. doc.subdocs.pull(4815162342); // works

    The first pull call will result in a atomic operation on the database, if pull is called repeatedly without saving the document, a $set operation is used on the complete array instead, overwriting possible changes that happened on the database in the meantime.

    MongooseArray.push([args...])

    Wraps Array#push with proper change tracking.

    Parameters:

    MongooseArray.set()

    Sets the casted val at index i and marks the array modified.

    Returns:

    Example:

    1. // given documents based on the following
    2. var Doc = mongoose.model('Doc', new Schema({ array: [Number] }));
    4. var doc = new Doc({ array: [2,3,4] })
    6. console.log(doc.array) // [2,3,4]
    8. doc.array.set(1,"5");
    9. console.log(doc.array); // [2,5,4] // properly cast to number
    10. doc.save() // the change is saved
    12. // VS not using array#set
    13. doc.array[1] = "5";
    14. console.log(doc.array); // [2,"5",4] // no casting
    15. doc.save() // change is not saved

    MongooseArray.shift()

    Wraps Array#shift with proper change tracking.

    Example:

    1. doc.array = [2,3];
    2. var res = doc.array.shift();
    3. console.log(res) // 2
    4. console.log(doc.array) // [3]

    Note:

    marks the entire array as modified, which if saved, will store it as a $set operation, potentially overwritting any changes that happen between when you retrieved the object and when you save it.

    MongooseArray.sort()

    Wraps Array#sort with proper change tracking.

    NOTE:

    marks the entire array as modified, which if saved, will store it as a $set operation, potentially overwritting any changes that happen between when you retrieved the object and when you save it.

    MongooseArray.splice()

    Wraps Array#splice with proper change tracking and casting.

    Note:

    marks the entire array as modified, which if saved, will store it as a $set operation, potentially overwritting any changes that happen between when you retrieved the object and when you save it.

    MongooseArray.toObject(options)

    Returns a native js Array.

    Parameters:

    Returns:

    MongooseArray.unshift()

    Wraps Array#unshift with proper change tracking.

    Note:

    marks the entire array as modified, which if saved, will store it as a $set operation, potentially overwritting any changes that happen between when you retrieved the object and when you save it.

    MongooseArray#_atomics

    Stores a queue of atomic operations to perform

    show code

    1. _atomics: undefined,

    MongooseArray#_parent

    Parent owner document

    show code

    1. _parent: undefined,

  • types/decimal128.js

    exports()

    ObjectId type constructor

    Example

    1. var id = new mongoose.Types.ObjectId;

  • types/objectid.js

    ObjectId()

    ObjectId type constructor

    Example

    1. var id = new mongoose.Types.ObjectId;

  • types/subdocument.js

    Subdocument#ownerDocument()

    Returns the top level document of this sub-document.

    Returns:

    show code

    1. Subdocument.prototype.ownerDocument = function() {
    2.   if (this.$__.ownerDocument) {
    3.     return this.$__.ownerDocument;
    4.   }
    6.   var parent = this.$parent;
    7.   if (!parent) {
    8.     return this;
    9.   }
    11.   while (parent.$parent || parent.__parent) {
    12.     parent = parent.$parent || parent.__parent;
    13.   }
    14.   this.$__.ownerDocument = parent;
    15.   return this.$__.ownerDocument;
    16. };

    Subdocument#parent()

    Returns this sub-documents parent document.

    show code

    1. Subdocument.prototype.parent = function() {
    2.   return this.$parent;
    3. };

    Subdocument#remove([options], [callback])

    Null-out this subdoc

    Parameters:

    • [options] <Object>
    • [callback] <Function> optional callback for compatibility with Document.prototype.remove

    show code

    1. Subdocument.prototype.remove = function(options, callback) {
    2.   if (typeof options === 'function') {
    3.     callback = options;
    4.     options = null;
    5.   }
    7.   registerRemoveListener(this);
    9.   // If removing entire doc, no need to remove subdoc
    10.   if (!options || !options.noop) {
    11.     this.$parent.set(this.$basePath, null);
    12.   }
    14.   if (typeof callback === 'function') {
    15.     callback(null);
    16.   }
    17. };

    Subdocument#save([fn])

    Used as a stub for hooks.js

    Parameters:

    Returns:

    NOTE:

    This is a no-op. Does not actually save the doc to the db.

    show code

    1. Subdocument.prototype.save = function(fn) {
    2.   var Promise = PromiseProvider.get();
    3.   return new Promise.ES6(function(resolve) {
    4.     fn && fn();
    5.     resolve();
    6.   });
    7. };
    9. Subdocument.prototype.$isValid = function(path) {
    10.   if (this.$parent && this.$basePath) {
    11.     return this.$parent.$isValid([this.$basePath, path].join('.'));
    12.   }
    13.   return Document.prototype.$isValid.call(this, path);
    14. };
    16. Subdocument.prototype.markModified = function(path) {
    17.   Document.prototype.markModified.call(this, path);
    18.   if (this.$parent && this.$basePath) {
    19.     if (this.$parent.isDirectModified(this.$basePath)) {
    20.       return;
    21.     }
    22.     this.$parent.markModified([this.$basePath, path].join('.'), this);
    23.   }
    24. };
    26. Subdocument.prototype.$markValid = function(path) {
    27.   Document.prototype.$markValid.call(this, path);
    28.   if (this.$parent && this.$basePath) {
    29.     this.$parent.$markValid([this.$basePath, path].join('.'));
    30.   }
    31. };
    33. Subdocument.prototype.invalidate = function(path, err, val) {
    34.   // Hack: array subdocuments' validationError is equal to the owner doc's,
    35.   // so validating an array subdoc gives the top-level doc back. Temporary
    36.   // workaround for #5208 so we don't have circular errors.
    37.   if (err !== this.ownerDocument().$__.validationError) {
    38.     Document.prototype.invalidate.call(this, path, err, val);
    39.   }
    41.   if (this.$parent && this.$basePath) {
    42.     this.$parent.invalidate([this.$basePath, path].join('.'), err, val);
    43.   } else if (err.kind === 'cast' || err.name === 'CastError') {
    44.     throw err;
    45.   }
    46. };

    Subdocument()

    Subdocument constructor.

    Inherits:

    show code

    1. function Subdocument(value, fields, parent, skipId, options) {
    2.   this.$isSingleNested = true;
    3.   Document.call(this, value, fields, skipId, options);
    4. }
    6. Subdocument.prototype = Object.create(Document.prototype);
    8. Subdocument.prototype.toBSON = function() {
    9.   return this.toObject({
    10.     transform: false,
    11.     virtuals: false,
    12.     _skipDepopulateTopLevel: true,
    13.     depopulate: true,
    14.     flattenDecimals: false
    15.   });
    16. };

  • types/embedded.js

    EmbeddedDocument#$__fullPath([path])

    Returns the full path to this document. If optional path is passed, it is appended to the full path.

    Parameters:

    Returns:

    EmbeddedDocument(obj, parentArr, skipId)

    EmbeddedDocument constructor.

    Parameters:

    Inherits:

    show code

    1. function EmbeddedDocument(obj, parentArr, skipId, fields, index) {
    2.   if (parentArr) {
    3.     this.__parentArray = parentArr;
    4.     this.__parent = parentArr._parent;
    5.   } else {
    6.     this.__parentArray = undefined;
    7.     this.__parent = undefined;
    8.   }
    9.   this.__index = index;
    11.   Document.call(this, obj, fields, skipId);
    13.   var _this = this;
    14.   this.on('isNew', function(val) {
    15.     _this.isNew = val;
    16.   });
    18.   _this.on('save', function() {
    19.     _this.constructor.emit('save', _this);
    20.   });
    21. }

    EmbeddedDocument#inspect()

    Helper for console.log

    show code

    1. EmbeddedDocument.prototype.inspect = function() {
    2.   return this.toObject({
    3.     transform: false,
    4.     retainKeyOrder: true,
    5.     virtuals: false,
    6.     flattenDecimals: false
    7.   });
    8. };

    EmbeddedDocument#invalidate(path, err)

    Marks a path as invalid, causing validation to fail.

    Parameters:

    • path <String> the field to invalidate
    • err <String, Error> error which states the reason path was invalid

    Returns:

    show code

    1. EmbeddedDocument.prototype.invalidate = function(path, err, val, first) {
    2.   if (!this.__parent) {
    3.     Document.prototype.invalidate.call(this, path, err, val);
    4.     if (err.$isValidatorError) {
    5.       return true;
    6.     }
    7.     throw err;
    8.   }
    10.   var index = this.__index;
    11.   if (typeof index !== 'undefined') {
    12.     var parentPath = this.__parentArray._path;
    13.     var fullPath = [parentPath, index, path].join('.');
    14.     this.__parent.invalidate(fullPath, err, val);
    15.   }
    17.   if (first) {
    18.     this.$__.validationError = this.ownerDocument().$__.validationError;
    19.   }
    21.   return true;
    22. };

    EmbeddedDocument#ownerDocument()

    Returns the top level document of this sub-document.

    Returns:

    show code

    1. EmbeddedDocument.prototype.ownerDocument = function() {
    2.   if (this.$__.ownerDocument) {
    3.     return this.$__.ownerDocument;
    4.   }
    6.   var parent = this.__parent;
    7.   if (!parent) {
    8.     return this;
    9.   }
    11.   while (parent.__parent || parent.$parent) {
    12.     parent = parent.__parent || parent.$parent;
    13.   }
    15.   this.$__.ownerDocument = parent;
    16.   return this.$__.ownerDocument;
    17. };

    EmbeddedDocument#parent()

    Returns this sub-documents parent document.

    show code

    1. EmbeddedDocument.prototype.parent = function() {
    2.   return this.__parent;
    3. };

    EmbeddedDocument#parentArray()

    Returns this sub-documents parent array.

    show code

    1. EmbeddedDocument.prototype.parentArray = function() {
    2.   return this.__parentArray;
    3. };

    EmbeddedDocument#remove([options], [fn])

    Removes the subdocument from its parent array.

    Parameters:

    show code

    1. EmbeddedDocument.prototype.remove = function(options, fn) {
    2.   if ( typeof options === 'function' && !fn ) {
    3.     fn = options;
    4.     options = undefined;
    5.   }
    6.   if (!this.__parentArray || (options && options.noop)) {
    7.     fn && fn(null);
    8.     return this;
    9.   }
    11.   var _id;
    12.   if (!this.willRemove) {
    13.     _id = this._doc._id;
    14.     if (!_id) {
    15.       throw new Error('For your own good, Mongoose does not know ' +
    16.           'how to remove an EmbeddedDocument that has no _id');
    17.     }
    18.     this.__parentArray.pull({_id: _id});
    19.     this.willRemove = true;
    20.     registerRemoveListener(this);
    21.   }
    23.   if (fn) {
    24.     fn(null);
    25.   }
    27.   return this;
    28. };

    EmbeddedDocument#save([fn])

    Used as a stub for hooks.js

    Parameters:

    Returns:

    NOTE:

    This is a no-op. Does not actually save the doc to the db.

    show code

    1. EmbeddedDocument.prototype.save = function(fn) {
    2.   var Promise = PromiseProvider.get();
    3.   return new Promise.ES6(function(resolve) {
    4.     fn && fn();
    5.     resolve();
    6.   });
    7. };

    EmbeddedDocument#update()

    Override #update method of parent documents.

    show code

    1. EmbeddedDocument.prototype.update = function() {
    2.   throw new Error('The #update method is not available on EmbeddedDocuments');
    3. };

    EmbeddedDocument.$isValid(path)

    Checks if a path is invalid

    Parameters:

    • path <String> the field to check

    EmbeddedDocument.$markValid(path)

    Marks a path as valid, removing existing validation errors.

    Parameters:

    • path <String> the field to mark as valid

    EmbeddedDocument.markModified(path)

    Marks the embedded doc modified.

    show code

    1. EmbeddedDocument.prototype.markModified = function(path) {
    2.   this.$__.activePaths.modify(path);
    3.   if (!this.__parentArray) {
    4.     return;
    5.   }
    7.   if (this.isNew) {
    8.     // Mark the WHOLE parent array as modified
    9.     // if this is a new document (i.e., we are initializing
    10.     // a document),
    11.     this.__parentArray._markModified();
    12.   } else {
    13.     this.__parentArray._markModified(this, path);
    14.   }
    15. };

    Parameters:

    • path <String> the path which changed

    Example:

    1. var doc = blogpost.comments.id(hexstring);
    2. doc.mixed.type = 'changed';
    3. doc.markModified('mixed.type');

  • types/buffer.js

    MongooseBuffer(value, encode, offset)

    Mongoose Buffer constructor.

    Parameters:

    Inherits:

    See:

    Values always have to be passed to the constructor to initialize.

    show code

    1. function MongooseBuffer(value, encode, offset) {
    2.   var length = arguments.length;
    3.   var val;
    5.   if (length === 0 || arguments[0] === null || arguments[0] === undefined) {
    6.     val = 0;
    7.   } else {
    8.     val = value;
    9.   }
    11.   var encoding;
    12.   var path;
    13.   var doc;
    15.   if (Array.isArray(encode)) {
    16.     // internal casting
    17.     path = encode[0];
    18.     doc = encode[1];
    19.   } else {
    20.     encoding = encode;
    21.   }
    23.   var buf = new Buffer(val, encoding, offset);
    24.   utils.decorate(buf, MongooseBuffer.mixin);
    25.   buf.isMongooseBuffer = true;
    27.   // make sure these internal props don't show up in Object.keys()
    28.   Object.defineProperties(buf, {
    29.     validators: {
    30.       value: [],
    31.       enumerable: false
    32.     },
    33.     _path: {
    34.       value: path,
    35.       enumerable: false
    36.     },
    37.     _parent: {
    38.       value: doc,
    39.       enumerable: false
    40.     }
    41.   });
    43.   if (doc && typeof path === 'string') {
    44.     Object.defineProperty(buf, '_schema', {
    45.       value: doc.schema.path(path)
    46.     });
    47.   }
    49.   buf._subtype = 0;
    50.   return buf;
    51. }

    MongooseBuffer._markModified()

    Marks this buffer as modified.

    MongooseBuffer.copy(target)

    Copies the buffer.

    Parameters:

    Returns:

    • <Number> The number of bytes copied.

    Note:

    Buffer#copy does not mark target as modified so you must copy from a MongooseBuffer for it to work as expected. This is a work around since copy modifies the target, not this.

    MongooseBuffer.equals(other)

    Determines if this buffer is equals to other buffer

    Parameters:

    Returns:

    MongooseBuffer.subtype(subtype)

    Sets the subtype option and marks the buffer modified.

    Parameters:

    See:

    SubTypes:

    var bson = require(‘bson’)
    bson.BSON_BINARY_SUBTYPE_DEFAULT
    bson.BSON_BINARY_SUBTYPE_FUNCTION
    bson.BSON_BINARY_SUBTYPE_BYTE_ARRAY
    bson.BSON_BINARY_SUBTYPE_UUID
    bson.BSON_BINARY_SUBTYPE_MD5
    bson.BSON_BINARY_SUBTYPE_USER_DEFINED

    doc.buffer.subtype(bson.BSON_BINARY_SUBTYPE_UUID);

    MongooseBuffer.toBSON()

    Converts this buffer for storage in MongoDB, including subtype

    Returns:

    MongooseBuffer.toObject([subtype])

    Converts this buffer to its Binary type representation.

    Parameters:

    • [subtype] <Hex>

    Returns:

    See:

    SubTypes:

    var bson = require(‘bson’)
    bson.BSON_BINARY_SUBTYPE_DEFAULT
    bson.BSON_BINARY_SUBTYPE_FUNCTION
    bson.BSON_BINARY_SUBTYPE_BYTE_ARRAY
    bson.BSON_BINARY_SUBTYPE_UUID
    bson.BSON_BINARY_SUBTYPE_MD5
    bson.BSON_BINARY_SUBTYPE_USER_DEFINED

    doc.buffer.toObject(bson.BSON_BINARY_SUBTYPE_USER_DEFINED);

    MongooseBuffer.write()

    Writes the buffer.

    MongooseBuffer#_parent

    Parent owner document

    show code

    1. _parent: undefined,

    MongooseBuffer#_subtype

    Default subtype for the Binary representing this Buffer

    show code

    1. _subtype: undefined,

  • document_provider.js

    module.exports()

    Returns the Document constructor for the current context

    show code

    1. module.exports = function() {
    2.   if (isBrowser) {
    3.     return BrowserDocument;
    4.   }
    5.   return Document;
    6. };

  • cast.js

    module.exports(schema, obj, options, context)

    Handles internal casting for query filters.

    show code

    1. module.exports = function cast(schema, obj, options, context) {
    2.   if (Array.isArray(obj)) {
    3.     throw new Error('Query filter must be an object, got an array ', util.inspect(obj));
    4.   }
    6.   var paths = Object.keys(obj);
    7.   var i = paths.length;
    8.   var _keys;
    9.   var any$conditionals;
    10.   var schematype;
    11.   var nested;
    12.   var path;
    13.   var type;
    14.   var val;
    16.   while (i--) {
    17.     path = paths[i];
    18.     val = obj[path];
    20.     if (path === '$or' || path === '$nor' || path === '$and') {
    21.       var k = val.length;
    23.       while (k--) {
    24.         val[k] = cast(schema, val[k], options, context);
    25.       }
    26.     } else if (path === '$where') {
    27.       type = typeof val;
    29.       if (type !== 'string' && type !== 'function') {
    30.         throw new Error('Must have a string or function for $where');
    31.       }
    33.       if (type === 'function') {
    34.         obj[path] = val.toString();
    35.       }
    37.       continue;
    38.     } else if (path === '$elemMatch') {
    39.       val = cast(schema, val, options, context);
    40.     } else {
    41.       if (!schema) {
    42.         // no casting for Mixed types
    43.         continue;
    44.       }
    46.       schematype = schema.path(path);
    48.       if (!schematype) {
    49.         // Handle potential embedded array queries
    50.         var split = path.split('.'),
    51.             j = split.length,
    52.             pathFirstHalf,
    53.             pathLastHalf,
    54.             remainingConds;
    56.         // Find the part of the var path that is a path of the Schema
    57.         while (j--) {
    58.           pathFirstHalf = split.slice(0, j).join('.');
    59.           schematype = schema.path(pathFirstHalf);
    60.           if (schematype) {
    61.             break;
    62.           }
    63.         }
    65.         // If a substring of the input path resolves to an actual real path...
    66.         if (schematype) {
    67.           // Apply the casting; similar code for $elemMatch in schema/array.js
    68.           if (schematype.caster && schematype.caster.schema) {
    69.             remainingConds = {};
    70.             pathLastHalf = split.slice(j).join('.');
    71.             remainingConds[pathLastHalf] = val;
    72.             obj[path] = cast(schematype.caster.schema, remainingConds, options, context)[pathLastHalf];
    73.           } else {
    74.             obj[path] = val;
    75.           }
    76.           continue;
    77.         }
    79.         if (utils.isObject(val)) {
    80.           // handle geo schemas that use object notation
    81.           // { loc: { long: Number, lat: Number }
    83.           var geo = '';
    84.           if (val.$near) {
    85.             geo = '$near';
    86.           } else if (val.$nearSphere) {
    87.             geo = '$nearSphere';
    88.           } else if (val.$within) {
    89.             geo = '$within';
    90.           } else if (val.$geoIntersects) {
    91.             geo = '$geoIntersects';
    92.           } else if (val.$geoWithin) {
    93.             geo = '$geoWithin';
    94.           }
    96.           if (geo) {
    97.             var numbertype = new Types.Number('__QueryCasting__');
    98.             var value = val[geo];
    100.             if (val.$maxDistance != null) {
    101.               val.$maxDistance = numbertype.castForQueryWrapper({
    102.                 val: val.$maxDistance,
    103.                 context: context
    104.               });
    105.             }
    106.             if (val.$minDistance != null) {
    107.               val.$minDistance = numbertype.castForQueryWrapper({
    108.                 val: val.$minDistance,
    109.                 context: context
    110.               });
    111.             }
    113.             if (geo === '$within') {
    114.               var withinType = value.$center
    115.                   || value.$centerSphere
    116.                   || value.$box
    117.                   || value.$polygon;
    119.               if (!withinType) {
    120.                 throw new Error('Bad $within paramater: ' + JSON.stringify(val));
    121.               }
    123.               value = withinType;
    124.             } else if (geo === '$near' &&
    125.                 typeof value.type === 'string' && Array.isArray(value.coordinates)) {
    126.               // geojson; cast the coordinates
    127.               value = value.coordinates;
    128.             } else if ((geo === '$near' || geo === '$nearSphere' || geo === '$geoIntersects') &&
    129.                 value.$geometry && typeof value.$geometry.type === 'string' &&
    130.                 Array.isArray(value.$geometry.coordinates)) {
    131.               if (value.$maxDistance != null) {
    132.                 value.$maxDistance = numbertype.castForQueryWrapper({
    133.                   val: value.$maxDistance,
    134.                   context: context
    135.                 });
    136.               }
    137.               if (value.$minDistance != null) {
    138.                 value.$minDistance = numbertype.castForQueryWrapper({
    139.                   val: value.$minDistance,
    140.                   context: context
    141.                 });
    142.               }
    143.               if (utils.isMongooseObject(value.$geometry)) {
    144.                 value.$geometry = value.$geometry.toObject({
    145.                   transform: false,
    146.                   virtuals: false
    147.                 });
    148.               }
    149.               value = value.$geometry.coordinates;
    150.             } else if (geo === '$geoWithin') {
    151.               if (value.$geometry) {
    152.                 if (utils.isMongooseObject(value.$geometry)) {
    153.                   value.$geometry = value.$geometry.toObject({ virtuals: false });
    154.                 }
    155.                 var geoWithinType = value.$geometry.type;
    156.                 if (ALLOWED_GEOWITHIN_GEOJSON_TYPES.indexOf(geoWithinType) === -1) {
    157.                   throw new Error('Invalid geoJSON type for $geoWithin "' +
    158.                     geoWithinType + '", must be "Polygon" or "MultiPolygon"');
    159.                 }
    160.                 value = value.$geometry.coordinates;
    161.               } else {
    162.                 value = value.$box || value.$polygon || value.$center ||
    163.                   value.$centerSphere;
    164.                 if (utils.isMongooseObject(value)) {
    165.                   value = value.toObject({ virtuals: false });
    166.                 }
    167.               }
    168.             }
    170.             _cast(value, numbertype, context);
    171.             continue;
    172.           }
    173.         }
    175.         if (options && options.upsert && options.strict && !schema.nested[path]) {
    176.           if (options.strict === 'throw') {
    177.             throw new StrictModeError(path);
    178.           }
    179.           throw new StrictModeError(path, 'Path "' + path + '" is not in ' +
    180.             'schema, strict mode is `true`, and upsert is `true`.');
    181.         } else if (options && options.strictQuery === 'throw') {
    182.           throw new StrictModeError(path, 'Path "' + path + '" is not in ' +
    183.             'schema and strictQuery is true.');
    184.         }
    185.       } else if (val === null || val === undefined) {
    186.         obj[path] = null;
    187.         continue;
    188.       } else if (val.constructor.name === 'Object') {
    189.         any$conditionals = Object.keys(val).some(function(k) {
    190.           return k.charAt(0) === '$' && k !== '$id' && k !== '$ref';
    191.         });
    193.         if (!any$conditionals) {
    194.           obj[path] = schematype.castForQueryWrapper({
    195.             val: val,
    196.             context: context
    197.           });
    198.         } else {
    199.           var ks = Object.keys(val),
    200.               $cond;
    202.           k = ks.length;
    204.           while (k--) {
    205.             $cond = ks[k];
    206.             nested = val[$cond];
    208.             if ($cond === '$not') {
    209.               if (nested && schematype && !schematype.caster) {
    210.                 _keys = Object.keys(nested);
    211.                 if (_keys.length && _keys[0].charAt(0) === '$') {
    212.                   for (var key in nested) {
    213.                     nested[key] = schematype.castForQueryWrapper({
    214.                       $conditional: key,
    215.                       val: nested[key],
    216.                       context: context
    217.                     });
    218.                   }
    219.                 } else {
    220.                   val[$cond] = schematype.castForQueryWrapper({
    221.                     $conditional: $cond,
    222.                     val: nested,
    223.                     context: context
    224.                   });
    225.                 }
    226.                 continue;
    227.               }
    228.               cast(schematype.caster ? schematype.caster.schema : schema, nested, options, context);
    229.             } else {
    230.               val[$cond] = schematype.castForQueryWrapper({
    231.                 $conditional: $cond,
    232.                 val: nested,
    233.                 context: context
    234.               });
    235.             }
    236.           }
    237.         }
    238.       } else if (Array.isArray(val) && ['Buffer', 'Array'].indexOf(schematype.instance) === -1) {
    239.         var casted = [];
    240.         for (var valIndex = 0; valIndex < val.length; valIndex++) {
    241.           casted.push(schematype.castForQueryWrapper({
    242.             val: val[valIndex],
    243.             context: context
    244.           }));
    245.         }
    247.         obj[path] = { $in: casted };
    248.       } else {
    249.         obj[path] = schematype.castForQueryWrapper({
    250.           val: val,
    251.           context: context
    252.         });
    253.       }
    254.     }
    255.   }
    257.   return obj;
    258. };
    260. function _cast(val, numbertype, context) {
    261.   if (Array.isArray(val)) {
    262.     val.forEach(function(item, i) {
    263.       if (Array.isArray(item) || utils.isObject(item)) {
    264.         return _cast(item, numbertype, context);
    265.       }
    266.       val[i] = numbertype.castForQueryWrapper({ val: item, context: context });
    267.     });
    268.   } else {
    269.     var nearKeys = Object.keys(val);
    270.     var nearLen = nearKeys.length;
    271.     while (nearLen--) {
    272.       var nkey = nearKeys[nearLen];
    273.       var item = val[nkey];
    274.       if (Array.isArray(item) || utils.isObject(item)) {
    275.         _cast(item, numbertype, context);
    276.         val[nkey] = item;
    277.       } else {
    278.         val[nkey] = numbertype.castForQuery({ val: item, context: context });
    279.       }
    280.     }
    281.   }
    282. }

    Parameters:

  • document.js

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

    Builds the default doc structure

    Parameters:

    Returns:

    Document#$__dirty()

    Returns this documents dirty paths / vals.

    Document#$__fullPath([path])

    Returns the full path to this document.

    Parameters:

    Returns:

    Document#$__getAllSubdocs()

    Get all subdocs (by bfs)

    Document#$__getArrayPathsToValidate()

    Get active path that were changed and are arrays

    Document#$__path(path)

    Returns the schematype for the given path.

    Parameters:

    Document#$__reset()

    Resets the internal modified state of this document.

    Returns:

    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:

    Document#$__shouldModify()

    Determine if we should mark this change as modified.

    Returns:

    Document#$ignore(path)

    Don’t run validation on this path or persist changes to this path.

    Parameters:

    • path <String> the path to ignore

    Example:

    1. doc.foo = null;
    2. doc.$ignore('foo');
    3. doc.save() // changes to foo will not be persisted and validators won't be run

    Document#$isDefault([path])

    Checks if a path is set to its default.

    Parameters:

    Returns:

    Example

    1. MyModel = mongoose.model('test', { name: { type: String, default: 'Val '} });
    2. var m = new MyModel();
    3. m.$isDefault('name'); // true

    function Object() { [native code] }#$isDeleted([val])%20%7B%20%5Bnative%20code%5D%20%7D-%24isDeleted)

    Getter/setter, determines whether the document was removed or not.

    Parameters:

    • [val] <Boolean> optional, overrides whether mongoose thinks the doc is deleted

    Returns:

    • <Boolean> whether mongoose thinks this doc is deleted.

    Example:

    1. product.remove(function (err, product) {
    2.   product.isDeleted(); // true
    3.   product.remove(); // no-op, doesn't send anything to the db
    5.   product.isDeleted(false);
    6.   product.isDeleted(); // false
    7.   product.remove(); // will execute a remove against the db
    8. })

    function Object() { [native code] }#$set(path, val, [type], [options])%20%7B%20%5Bnative%20code%5D%20%7D-%24set)

    Alias for set(), used internally to avoid conflicts

    Parameters:

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

    Document#$toObject()

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

    Document#depopulate(path)

    Takes a populated field and returns it to its unpopulated state.

    Parameters:

    Returns:

    See:

    Example:

    1. Model.findOne().populate('author').exec(function (err, doc) {
    2.   console.log(doc.author.name); // Dr.Seuss
    3.   console.log(doc.depopulate('author'));
    4.   console.log(doc.author); // '5144cf8050f071d979c118a7'
    5. })

    If the path was not populated, this is a no-op.

    show code

    1. Document.prototype.depopulate = function(path) {
    2.   if (typeof path === 'string') {
    3.     path = path.split(' ');
    4.   }
    5.   for (var i = 0; i < path.length; i++) {
    6.     var populatedIds = this.populated(path[i]);
    7.     if (!populatedIds) {
    8.       continue;
    9.     }
    10.     delete this.$__.populated[path[i]];
    11.     this.$set(path[i], populatedIds);
    12.   }
    13.   return this;
    14. };

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

    Document constructor.

    Parameters:

    • obj <Object> the values to set
    • [fields] <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:

    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

    1. function Document(obj, fields, skipId, options) {
    2.   this.$__ = new InternalCache;
    3.   this.$__.emitter = new EventEmitter();
    4.   this.isNew = true;
    5.   this.errors = undefined;
    6.   this.$__.$options = options || {};
    8.   if (obj != null && typeof obj !== 'object') {
    9.     throw new ObjectParameterError(obj, 'obj', 'Document');
    10.   }
    12.   var schema = this.schema;
    14.   if (typeof fields === 'boolean') {
    15.     this.$__.strictMode = fields;
    16.     fields = undefined;
    17.   } else {
    18.     this.$__.strictMode = schema.options && schema.options.strict;
    19.     this.$__.selected = fields;
    20.   }
    22.   var required = schema.requiredPaths(true);
    23.   for (var i = 0; i < required.length; ++i) {
    24.     this.$__.activePaths.require(required[i]);
    25.   }
    27.   this.$__.emitter.setMaxListeners(0);
    28.   this._doc = this.$__buildDoc(obj, fields, skipId);
    30.   if (obj) {
    31.     if (obj instanceof Document) {
    32.       this.isNew = obj.isNew;
    33.     }
    34.     // Skip set hooks
    35.     if (this.$__original_set) {
    36.       this.$__original_set(obj, undefined, true);
    37.     } else {
    38.       this.$set(obj, undefined, true);
    39.     }
    40.   }
    42.   this.$__._id = this._id;
    44.   if (!schema.options.strict && obj) {
    45.     var _this = this,
    46.         keys = Object.keys(this._doc);
    48.     keys.forEach(function(key) {
    49.       if (!(key in schema.tree)) {
    50.         defineKey(key, null, _this);
    51.       }
    52.     });
    53.   }
    55.   applyQueue(this);
    56. }

    Document#equals(doc)

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

    Parameters:

    Returns:

    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

    1. Document.prototype.equals = function(doc) {
    2.   if (!doc) {
    3.     return false;
    4.   }
    6.   var tid = this.get('_id');
    7.   var docid = doc.get ? doc.get('_id') : doc;
    8.   if (!tid && !docid) {
    9.     return deepEqual(this, doc);
    10.   }
    11.   return tid && tid.equals
    12.       ? tid.equals(docid)
    13.       : tid === docid;
    14. };

    Document#execPopulate()

    Explicitly executes population and returns a promise. Useful for ES2015
    integration.

    Returns:

    • <Promise> promise that resolves to the document when population is done

    See:

    Example:

    1. var promise = doc.
    2.   populate('company').
    3.   populate({
    4.     path: 'notes',
    5.     match: /airline/,
    6.     select: 'text',
    7.     model: 'modelName'
    8.     options: opts
    9.   }).
    10.   execPopulate();
    12. // summary
    13. doc.execPopulate().then(resolve, reject);

    show code

    1. Document.prototype.execPopulate = function() {
    2.   var Promise = PromiseProvider.get();
    3.   var _this = this;
    4.   return new Promise.ES6(function(resolve, reject) {
    5.     _this.populate(function(error, res) {
    6.       if (error) {
    7.         reject(error);
    8.       } else {
    9.         resolve(res);
    10.       }
    11.     });
    12.   });
    13. };

    Document#get(path, [type])

    Returns the value of a path.

    Parameters:

    Example

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

    show code

    1. Document.prototype.get = function(path, type) {
    2.   var adhoc;
    3.   if (type) {
    4.     adhoc = Schema.interpretAsType(path, type, this.schema.options);
    5.   }
    7.   var schema = this.$__path(path) || this.schema.virtualpath(path);
    8.   var pieces = path.split('.');
    9.   var obj = this._doc;
    11.   if (schema instanceof VirtualType) {
    12.     if (schema.getters.length === 0) {
    13.       return void 0;
    14.     }
    15.     return schema.applyGetters(null, this);
    16.   }
    18.   for (var i = 0, l = pieces.length; i < l; i++) {
    19.     obj = obj === null || obj === void 0
    20.         ? undefined
    21.         : obj[pieces[i]];
    22.   }
    24.   if (adhoc) {
    25.     obj = adhoc.cast(obj);
    26.   }
    28.   if (schema) {
    29.     obj = schema.applyGetters(obj, this);
    30.   }
    32.   return obj;
    33. };

    Document#getValue(path)

    Gets a raw value from a path (no getters)

    Parameters:

    show code

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

    Document#init(doc, fn)

    Initializes the document without setters or marking anything modified.

    Parameters:

    Called internally after a document is returned from mongodb.

    show code

    1. Document.prototype.init = function(doc, opts, fn) {
    2.   // do not prefix this method with $__ since its
    3.   // used by public hooks
    5.   if (typeof opts === 'function') {
    6.     fn = opts;
    7.     opts = null;
    8.   }
    10.   this.isNew = false;
    11.   this.$init = true;
    13.   // handle docs with populated paths
    14.   // If doc._id is not null or undefined
    15.   if (doc._id !== null && doc._id !== undefined &&
    16.     opts && opts.populated && opts.populated.length) {
    17.     var id = String(doc._id);
    18.     for (var i = 0; i < opts.populated.length; ++i) {
    19.       var item = opts.populated[i];
    20.       if (item.isVirtual) {
    21.         this.populated(item.path, utils.getValue(item.path, doc), item);
    22.       } else {
    23.         this.populated(item.path, item._docs[id], item);
    24.       }
    25.     }
    26.   }
    28.   init(this, doc, this._doc);
    30.   this.emit('init', this);
    31.   this.constructor.emit('init', this);
    33.   this.$__._id = this._id;
    35.   if (fn) {
    36.     fn(null);
    37.   }
    38.   return this;
    39. };

    Document#inspect()

    Helper for console.log

    show code

    1. Document.prototype.inspect = function(options) {
    2.   var isPOJO = options &&
    3.     utils.getFunctionName(options.constructor) === 'Object';
    4.   var opts;
    5.   if (isPOJO) {
    6.     opts = options;
    7.     opts.minimize = false;
    8.     opts.retainKeyOrder = true;
    9.   }
    10.   return this.toObject(opts);
    11. };

    Document#invalidate(path, errorMsg, value, [kind])

    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
    • [kind] <String> optional kind property for the error

    Returns:

    • <ValidationError> the current ValidationError, with all currently invalidated paths

    The errorMsg argument will become the message of the ValidationError.

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

    1. doc.invalidate('size', 'must be less than 20', 14);
    3. doc.validate(function (err) {
    4.   console.log(err)
    5.   // prints
    6.   { message: 'Validation failed',
    7.     name: 'ValidationError',
    8.     errors:
    9.      { size:
    10.         { message: 'must be less than 20',
    11.           name: 'ValidatorError',
    12.           path: 'size',
    13.           type: 'user defined',
    14.           value: 14 } } }
    15. })

    show code

    1. Document.prototype.invalidate = function(path, err, val, kind) {
    2.   if (!this.$__.validationError) {
    3.     this.$__.validationError = new ValidationError(this);
    4.   }
    6.   if (this.$__.validationError.errors[path]) {
    7.     return;
    8.   }
    10.   if (!err || typeof err === 'string') {
    11.     err = new ValidatorError({
    12.       path: path,
    13.       message: err,
    14.       type: kind || 'user defined',
    15.       value: val
    16.     });
    17.   }
    19.   if (this.$__.validationError === err) {
    20.     return this.$__.validationError;
    21.   }
    23.   this.$__.validationError.addError(path, err);
    24.   return this.$__.validationError;
    25. };

    Document#isDirectModified(path)

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

    Parameters:

    Returns:

    Example

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

    show code

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

    Document#isDirectSelected(path)

    Checks if path was explicitly selected. If no projection, always returns
    true.

    Parameters:

    Returns:

    Example

    1. Thing.findOne().select('nested.name').exec(function (err, doc) {
    2.    doc.isDirectSelected('nested.name') // true
    3.    doc.isDirectSelected('nested.otherName') // false
    4.    doc.isDirectSelected('nested')  // false
    5. })

    show code

    1. Document.prototype.isDirectSelected = function isDirectSelected(path) {
    2.   if (this.$__.selected) {
    3.     if (path === '_id') {
    4.       return this.$__.selected._id !== 0;
    5.     }
    7.     var paths = Object.keys(this.$__.selected);
    8.     var i = paths.length;
    9.     var inclusive = null;
    10.     var cur;
    12.     if (i === 1 && paths[0] === '_id') {
    13.       // only _id was selected.
    14.       return this.$__.selected._id === 0;
    15.     }
    17.     while (i--) {
    18.       cur = paths[i];
    19.       if (cur === '_id') {
    20.         continue;
    21.       }
    22.       if (!isDefiningProjection(this.$__.selected[cur])) {
    23.         continue;
    24.       }
    25.       inclusive = !!this.$__.selected[cur];
    26.       break;
    27.     }
    29.     if (inclusive === null) {
    30.       return true;
    31.     }
    33.     if (path in this.$__.selected) {
    34.       return inclusive;
    35.     }
    37.     return !inclusive;
    38.   }
    40.   return true;
    41. };

    Document#isInit(path)

    Checks if path was initialized.

    Parameters:

    Returns:

    show code

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

    Document#isModified([path])

    Returns true if this document was modified, else false.

    Parameters:

    Returns:

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

    Example

    1. doc.set('documents.0.title', 'changed');
    2. doc.isModified()                      // true
    3. doc.isModified('documents')           // true
    4. doc.isModified('documents.0.title')   // true
    5. doc.isModified('documents otherProp') // true
    6. doc.isDirectModified('documents')     // false

    show code

    1. Document.prototype.isModified = function(paths) {
    2.   if (paths) {
    3.     if (!Array.isArray(paths)) {
    4.       paths = paths.split(' ');
    5.     }
    6.     var modified = this.modifiedPaths();
    7.     var directModifiedPaths = Object.keys(this.$__.activePaths.states.modify);
    8.     var isModifiedChild = paths.some(function(path) {
    9.       return !!~modified.indexOf(path);
    10.     });
    11.     return isModifiedChild || paths.some(function(path) {
    12.       return directModifiedPaths.some(function(mod) {
    13.         return mod === path || path.indexOf(mod + '.') === 0;
    14.       });
    15.     });
    16.   }
    17.   return this.$__.activePaths.some('modify');
    18. };

    Document#isSelected(path)

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

    Parameters:

    Returns:

    Example

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

    show code

    1. Document.prototype.isSelected = function isSelected(path) {
    2.   if (this.$__.selected) {
    3.     if (path === '_id') {
    4.       return this.$__.selected._id !== 0;
    5.     }
    7.     var paths = Object.keys(this.$__.selected);
    8.     var i = paths.length;
    9.     var inclusive = null;
    10.     var cur;
    12.     if (i === 1 && paths[0] === '_id') {
    13.       // only _id was selected.
    14.       return this.$__.selected._id === 0;
    15.     }
    17.     while (i--) {
    18.       cur = paths[i];
    19.       if (cur === '_id') {
    20.         continue;
    21.       }
    22.       if (!isDefiningProjection(this.$__.selected[cur])) {
    23.         continue;
    24.       }
    25.       inclusive = !!this.$__.selected[cur];
    26.       break;
    27.     }
    29.     if (inclusive === null) {
    30.       return true;
    31.     }
    33.     if (path in this.$__.selected) {
    34.       return inclusive;
    35.     }
    37.     i = paths.length;
    38.     var pathDot = path + '.';
    40.     while (i--) {
    41.       cur = paths[i];
    42.       if (cur === '_id') {
    43.         continue;
    44.       }
    46.       if (cur.indexOf(pathDot) === 0) {
    47.         return inclusive || cur !== pathDot;
    48.       }
    50.       if (pathDot.indexOf(cur + '.') === 0) {
    51.         return inclusive;
    52.       }
    53.     }
    55.     return !inclusive;
    56.   }
    58.   return true;
    59. };

    Document#markModified(path, [scope])

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

    Parameters:

    • path <String> the path to mark modified
    • [scope] <Document> the scope to run validators with

    Very helpful when using Mixed types.

    Example:

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

    show code

    1. Document.prototype.markModified = function(path, scope) {
    2.   this.$__.activePaths.modify(path);
    3.   if (scope != null && !this.ownerDocument) {
    4.     this.$__.pathsToScopes[path] = scope;
    5.   }
    6. };

    Document#modifiedPaths()

    Returns the list of paths that have been modified.

    Returns:

    show code

    1. Document.prototype.modifiedPaths = function() {
    2.   var directModifiedPaths = Object.keys(this.$__.activePaths.states.modify);
    3.   return directModifiedPaths.reduce(function(list, path) {
    4.     var parts = path.split('.');
    5.     return list.concat(parts.reduce(function(chains, part, i) {
    6.       return chains.concat(parts.slice(0, i).concat(part).join('.'));
    7.     }, []).filter(function(chain) {
    8.       return (list.indexOf(chain) === -1);
    9.     }));
    10.   }, []);
    11. };

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

    Populates document references, executing the callback when complete.
    If you want to use promises instead, use this function with
    execPopulate()

    Parameters:

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

    Returns:

    See:

    Example:

    1. doc
    2. .populate('company')
    3. .populate({
    4.   path: 'notes',
    5.   match: /airline/,
    6.   select: 'text',
    7.   model: 'modelName'
    8.   options: opts
    9. }, function (err, user) {
    10.   assert(doc._id === user._id) // the document itself is passed
    11. })
    13. // summary
    14. doc.populate(path)                   // not executed
    15. doc.populate(options);               // not executed
    16. doc.populate(path, callback)         // executed
    17. doc.populate(options, callback);     // executed
    18. doc.populate(callback);              // executed
    19. doc.populate(options).execPopulate() // executed, returns promise

    NOTE:

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

    show code

    1. Document.prototype.populate = function populate() {
    2.   if (arguments.length === 0) {
    3.     return this;
    4.   }
    6.   var pop = this.$__.populate || (this.$__.populate = {});
    7.   var args = utils.args(arguments);
    8.   var fn;
    10.   if (typeof args[args.length - 1] === 'function') {
    11.     fn = args.pop();
    12.   }
    14.   // allow `doc.populate(callback)`
    15.   if (args.length) {
    16.     // use hash to remove duplicate paths
    17.     var res = utils.populate.apply(null, args);
    18.     for (var i = 0; i < res.length; ++i) {
    19.       pop[res[i].path] = res[i];
    20.     }
    21.   }
    23.   if (fn) {
    24.     var paths = utils.object.vals(pop);
    25.     this.$__.populate = undefined;
    26.     paths.__noPromise = true;
    27.     var topLevelModel = this.constructor;
    28.     if (this.$__isNested) {
    29.       topLevelModel = this.$__.scope.constructor;
    30.       var nestedPath = this.$__.nestedPath;
    31.       paths.forEach(function(populateOptions) {
    32.         populateOptions.path = nestedPath + '.' + populateOptions.path;
    33.       });
    34.     }
    35.     topLevelModel.populate(this, paths, fn);
    36.   }
    38.   return this;
    39. };

    Document#populated(path)

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

    Parameters:

    Returns:

    Example:

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

    If the path was not populated, undefined is returned.

    show code

    1. Document.prototype.populated = function(path, val, options) {
    2.   // val and options are internal
    4.   if (val === null || val === void 0) {
    5.     if (!this.$__.populated) {
    6.       return undefined;
    7.     }
    8.     var v = this.$__.populated[path];
    9.     if (v) {
    10.       return v.value;
    11.     }
    12.     return undefined;
    13.   }
    15.   // internal
    17.   if (val === true) {
    18.     if (!this.$__.populated) {
    19.       return undefined;
    20.     }
    21.     return this.$__.populated[path];
    22.   }
    24.   this.$__.populated || (this.$__.populated = {});
    25.   this.$__.populated[path] = {value: val, options: options};
    26.   return val;
    27. };

    function Object() { [native code] }#save([options], [options.safe], [options.validateBeforeSave], [fn])%20%7B%20%5Bnative%20code%5D%20%7D-save)

    Saves this document.

    Parameters:

    Returns:

    See:

    Example:

    1. product.sold = Date.now();
    2. product.save(function (err, product, numAffected) {
    3.   if (err) ..
    4. })

    The callback will receive three parameters

    1. err if an error occurred
    2. product which is the saved product
    3. numAffected will be 1 when the document was successfully persisted to MongoDB, otherwise 0. Unless you tweak mongoose’s internals, you don’t need to worry about checking this parameter for errors - checking err is sufficient to make sure your document was properly saved.

    As an extra measure of flow control, save will return a Promise.

    Example:

    1. product.save().then(function(product) {
    2.    ...
    3. });

    For legacy reasons, mongoose stores object keys in reverse order on initial
    save. That is, { a: 1, b: 2 } will be saved as { b: 2, a: 1 } in
    MongoDB. To override this behavior, set
    the toObject.retainKeyOrder option
    to true on your schema.

    (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, *> optionally specify a type for “on-the-fly” attributes
    • [options] <Object> optionally specify options that modify the behavior of the set

    Example:

    1. // path, value
    2. doc.set(path, value)
    4. // object
    5. doc.set({
    6.     path  : value
    7.   , path2 : {
    8.        path  : value
    9.     }
    10. })
    12. // on-the-fly cast to number
    13. doc.set(path, value, Number)
    15. // on-the-fly cast to string
    16. doc.set(path, value, String)
    18. // changing strict mode behavior
    19. doc.set(path, value, { strict: false });

    show code

    1. Document.prototype.set = Document.prototype.$set;

    Document#setValue(path, value)

    Sets a raw value for a path (no casting, setters, transformations)

    Parameters:

    show code

    1. Document.prototype.setValue = function(path, val) {
    2.   utils.setValue(path, val, this._doc);
    3.   return this;
    4. };

    Document#toJSON(options)

    The return value of this method is used in calls to JSON.stringify(doc).

    Parameters:

    Returns:

    See:

    This method accepts the same options as Document#toObject. To apply the options to every document of your schema by default, set your schemas toJSON option to the same argument.

    1. schema.set('toJSON', { virtuals: true })

    See schema options for details.

    show code

    1. Document.prototype.toJSON = function(options) {
    2.   return this.$toObject(options, true);
    3. };

    Document#toObject([options])

    Converts this document into a plain javascript object, ready for storage in MongoDB.

    Parameters:

    Returns:

    See:

    Buffers are converted to instances of mongodb.Binary for proper storage.

    Options:

    • getters apply all getters (path and virtual getters)
    • virtuals apply virtual getters (can override getters option)
    • minimize remove empty objects (defaults to true)
    • transform a transform function to apply to the resulting document before returning
    • depopulate depopulate any populated paths, replacing them with their original refs (defaults to false)
    • versionKey whether to include the version key (defaults to true)
    • retainKeyOrder keep the order of object keys. If this is set to true, Object.keys(new Doc({ a: 1, b: 2}).toObject()) will always produce ['a', 'b'] (defaults to false)

    Getters/Virtuals

    Example of only applying path getters

    1. doc.toObject({ getters: true, virtuals: false })

    Example of only applying virtual getters

    1. doc.toObject({ virtuals: true })

    Example of applying both path and virtual getters

    1. doc.toObject({ getters: true })

    To apply these options to every document of your schema by default, set your schemas toObject option to the same argument.

    1. schema.set('toObject', { virtuals: true })

    Transform

    We may need to perform a transformation of the resulting object based on some criteria, say to remove some sensitive information or return a custom object. In this case we set the optional transform function.

    Transform functions receive three arguments

    1. function (doc, ret, options) {}
    • doc The mongoose document which is being converted
    • ret The plain object representation which has been converted
    • options The options in use (either schema options or the options passed inline)

    Example

    1. // specify the transform schema option
    2. if (!schema.options.toObject) schema.options.toObject = {};
    3. schema.options.toObject.transform = function (doc, ret, options) {
    4.   // remove the _id of every document before returning the result
    5.   delete ret._id;
    6.   return ret;
    7. }
    9. // without the transformation in the schema
    10. doc.toObject(); // { _id: 'anId', name: 'Wreck-it Ralph' }
    12. // with the transformation
    13. doc.toObject(); // { name: 'Wreck-it Ralph' }

    With transformations we can do a lot more than remove properties. We can even return completely new customized objects:

    1. if (!schema.options.toObject) schema.options.toObject = {};
    2. schema.options.toObject.transform = function (doc, ret, options) {
    3.   return { movie: ret.name }
    4. }
    6. // without the transformation in the schema
    7. doc.toObject(); // { _id: 'anId', name: 'Wreck-it Ralph' }
    9. // with the transformation
    10. doc.toObject(); // { movie: 'Wreck-it Ralph' }

    Note: if a transform function returns undefined, the return value will be ignored.

    Transformations may also be applied inline, overridding any transform set in the options:

    1. function xform (doc, ret, options) {
    2.   return { inline: ret.name, custom: true }
    3. }
    5. // pass the transform as an inline option
    6. doc.toObject({ transform: xform }); // { inline: 'Wreck-it Ralph', custom: true }

    If you want to skip transformations, use transform: false:

    1. if (!schema.options.toObject) schema.options.toObject = {};
    2. schema.options.toObject.hide = '_id';
    3. schema.options.toObject.transform = function (doc, ret, options) {
    4.   if (options.hide) {
    5.     options.hide.split(' ').forEach(function (prop) {
    6.       delete ret[prop];
    7.     });
    8.   }
    9.   return ret;
    10. }
    12. var doc = new Doc({ _id: 'anId', secret: 47, name: 'Wreck-it Ralph' });
    13. doc.toObject();                                        // { secret: 47, name: 'Wreck-it Ralph' }
    14. doc.toObject({ hide: 'secret _id', transform: false });// { _id: 'anId', secret: 47, name: 'Wreck-it Ralph' }
    15. doc.toObject({ hide: 'secret _id', transform: true }); // { name: 'Wreck-it Ralph' }

    Transforms are applied only to the document and are not applied to sub-documents.

    Transforms, like all of these options, are also available for toJSON.

    See schema options for some more details.

    During save, no custom options are applied to the document before being sent to the database.

    show code

    1. Document.prototype.toObject = function(options) {
    2.   return this.$toObject(options);
    3. };

    Document#toString()

    Helper for console.log

    Document#unmarkModified(path)

    Clears the modified state on the specified path.

    Parameters:

    • path <String> the path to unmark modified

    Example:

    1. doc.foo = 'bar';
    2. doc.unmarkModified('foo');
    3. doc.save() // changes to foo will not be persisted

    show code

    1. Document.prototype.unmarkModified = function(path) {
    2.   this.$__.activePaths.init(path);
    3.   delete this.$__.pathsToScopes[path];
    4. };

    Document#update(doc, options, callback)

    Sends an update command with this document _id as the query selector.

    Parameters:

    Returns:

    See:

    Example:

    1. weirdCar.update({$inc: {wheels:1}}, { w: 1 }, callback);

    Valid options:

    show code

    1. Document.prototype.update = function update() {
    2.   var args = utils.args(arguments);
    3.   args.unshift({_id: this._id});
    4.   return this.constructor.update.apply(this.constructor, args);
    5. };

    Document#validate(optional, callback)

    Executes registered validation rules for this document.

    Parameters:

    • optional <Object> options internal options
    • callback <Function> optional callback called after validation completes, passing an error if one occurred

    Returns:

    Note:

    This method is called pre save and if a validation rule is violated, save is aborted and the error is returned to your callback.

    Example:

    1. doc.validate(function (err) {
    2.   if (err) handleError(err);
    3.   else // validation passed
    4. });

    show code

    1. Document.prototype.validate = function(options, callback) {
    2.   if (typeof options === 'function') {
    3.     callback = options;
    4.     options = null;
    5.   }
    7.   this.$__validate(callback || function() {});
    8. };

    Document#validateSync(pathsToValidate)

    Executes registered validation rules (skipping asynchronous validators) for this document.

    Parameters:

    • pathsToValidate <Array, string> only validate the given paths

    Returns:

    • <MongooseError, undefined> MongooseError if there are errors during validation, or undefined if there is no error.

    Note:

    This method is useful if you need synchronous validation.

    Example:

    1. var err = doc.validateSync();
    2. if ( err ){
    3.   handleError( err );
    4. } else {
    5.   // validation passed
    6. }

    show code

    1. Document.prototype.validateSync = function(pathsToValidate) {
    2.   var _this = this;
    4.   if (typeof pathsToValidate === 'string') {
    5.     pathsToValidate = pathsToValidate.split(' ');
    6.   }
    8.   // only validate required fields when necessary
    9.   var paths = _getPathsToValidate(this);
    11.   if (pathsToValidate && pathsToValidate.length) {
    12.     var tmp = [];
    13.     for (var i = 0; i < paths.length; ++i) {
    14.       if (pathsToValidate.indexOf(paths[i]) !== -1) {
    15.         tmp.push(paths[i]);
    16.       }
    17.     }
    18.     paths = tmp;
    19.   }
    21.   var validating = {};
    23.   paths.forEach(function(path) {
    24.     if (validating[path]) {
    25.       return;
    26.     }
    28.     validating[path] = true;
    30.     var p = _this.schema.path(path);
    31.     if (!p) {
    32.       return;
    33.     }
    34.     if (!_this.$isValid(path)) {
    35.       return;
    36.     }
    38.     var val = _this.getValue(path);
    39.     var err = p.doValidateSync(val, _this);
    40.     if (err) {
    41.       _this.invalidate(path, err, undefined, true);
    42.     }
    43.   });
    45.   var err = _this.$__.validationError;
    46.   _this.$__.validationError = undefined;
    47.   _this.emit('validate', _this);
    48.   _this.constructor.emit('validate', _this);
    50.   if (err) {
    51.     for (var key in err.errors) {
    52.       // Make sure cast errors persist
    53.       if (err.errors[key] instanceof MongooseError.CastError) {
    54.         _this.invalidate(key, err.errors[key]);
    55.       }
    56.     }
    57.   }
    59.   return err;
    60. };

    Document.$isValid(path)

    Checks if a path is invalid

    Parameters:

    • path <String> the field to check

    Document.$markValid(path)

    Marks a path as valid, removing existing validation errors.

    Parameters:

    • path <String> the field to mark as valid

    Document#errors

    Hash containing current validation errors.

    show code

    1. Document.prototype.errors;

    Document#id

    The string version of this documents _id.

    Note:

    This getter exists on all documents by default. The getter can be disabled by setting the id option of its Schema to false at construction time.

    1. new Schema({ name: String }, { id: false });

    show code

    1. Document.prototype.id;

    See:

    Document#isNew

    Boolean flag specifying if the document is new.

    show code

    1. Document.prototype.isNew;

    Document#schema

    The documents schema.

    show code

    1. Document.prototype.schema;

  • cursor/QueryCursor.js

    QueryCursor#addCursorFlag(flag, value)

    Adds a cursor flag.
    Useful for setting the noCursorTimeout and tailable flags.

    Parameters:

    Returns:

    QueryCursor#close(callback)

    Marks this cursor as closed. Will stop streaming and subsequent calls to
    next() will error.

    Parameters:

    Returns:

    See:

    QueryCursor#eachAsync(fn, [options], [options.parallel], [callback])

    Execute fn for every document in the cursor. If fn returns a promise,
    will wait for the promise to resolve before iterating on to the next one.
    Returns a promise that resolves when done.

    Parameters:

    • fn <Function>
    • [options] <Object>
    • [options.parallel] <Number> the number of promises to execute in parallel. Defaults to 1.
    • [callback] <Function> executed when all docs have been processed

    Returns:

    QueryCursor#map(fn)

    Registers a transform function which subsequently maps documents retrieved
    via the streams interface or .next()

    Parameters:

    Returns:

    Example

    1. // Map documents returned by `data` events
    2. Thing.
    3.   find({ name: /^hello/ }).
    4.   cursor().
    5.   map(function (doc) {
    6.    doc.foo = "bar";
    7.    return doc;
    8.   })
    9.   on('data', function(doc) { console.log(doc.foo); });
    11. // Or map documents returned by `.next()`
    12. var cursor = Thing.find({ name: /^hello/ }).
    13.   cursor().
    14.   map(function (doc) {
    15.     doc.foo = "bar";
    16.     return doc;
    17.   });
    18. cursor.next(function(error, doc) {
    19.   console.log(doc.foo);
    20. });

    QueryCursor#next(callback)

    Get the next document from this cursor. Will return null when there are
    no documents left.

    Parameters:

    Returns:

    QueryCursor(query, options)

    A QueryCursor is a concurrency primitive for processing query results
    one document at a time. A QueryCursor fulfills the Node.js streams3 API,
    in addition to several other mechanisms for loading documents from MongoDB
    one at a time.

    Parameters:

    • query <Query>
    • options <Object> query options passed to .find()

    Inherits:

    Events:

    • cursor: Emitted when the cursor is created

    • error: Emitted when an error occurred

    • data: Emitted when the stream is flowing and the next doc is ready

    • end: Emitted when the stream is exhausted

    QueryCursors execute the model’s pre find hooks, but not the model’s
    post find hooks.

    Unless you’re an advanced user, do not instantiate this class directly.
    Use Query#cursor() instead.

    show code

    1. function QueryCursor(query, options) {
    2.   Readable.call(this, { objectMode: true });
    4.   this.cursor = null;
    5.   this.query = query;
    6.   this._transforms = options.transform ? [options.transform] : [];
    7.   var _this = this;
    8.   var model = query.model;
    9.   model.hooks.execPre('find', query, function() {
    10.     model.collection.find(query._conditions, options, function(err, cursor) {
    11.       if (_this._error) {
    12.         cursor.close(function() {});
    13.         _this.listeners('error').length > 0 && _this.emit('error', _this._error);
    14.       }
    15.       if (err) {
    16.         return _this.emit('error', err);
    17.       }
    18.       _this.cursor = cursor;
    19.       _this.emit('cursor', cursor);
    20.     });
    21.   });
    22. }
    24. util.inherits(QueryCursor, Readable);

  • cursor/AggregationCursor.js

    AggregationCursor#addCursorFlag(flag, value)

    Adds a cursor flag.
    Useful for setting the noCursorTimeout and tailable flags.

    Parameters:

    Returns:

    AggregationCursor(agg, options)

    An AggregationCursor is a concurrency primitive for processing aggregation
    results one document at a time. It is analogous to QueryCursor.

    Parameters:

    Inherits:

    Events:

    • cursor: Emitted when the cursor is created

    • error: Emitted when an error occurred

    • data: Emitted when the stream is flowing and the next doc is ready

    • end: Emitted when the stream is exhausted

    An AggregationCursor fulfills the Node.js streams3 API,
    in addition to several other mechanisms for loading documents from MongoDB
    one at a time.

    Creating an AggregationCursor executes the model’s pre aggregate hooks,
    but not the model’s post aggregate hooks.

    Unless you’re an advanced user, do not instantiate this class directly.
    Use Aggregate#cursor() instead.

    show code

    1. function AggregationCursor(agg) {
    2.   Readable.call(this, { objectMode: true });
    4.   this.cursor = null;
    5.   this.agg = agg;
    6.   this._transforms = [];
    7.   var model = agg._model;
    8.   delete agg.options.cursor.useMongooseAggCursor;
    10.   _init(model, this, agg);
    11. }
    13. util.inherits(AggregationCursor, Readable);

    AggregationCursor#close(callback)

    Marks this cursor as closed. Will stop streaming and subsequent calls to
    next() will error.

    Parameters:

    Returns:

    See:

    AggregationCursor#eachAsync(fn, [callback])

    Execute fn for every document in the cursor. If fn returns a promise,
    will wait for the promise to resolve before iterating on to the next one.
    Returns a promise that resolves when done.

    Parameters:

    Returns:

    AggregationCursor#map(fn)

    Registers a transform function which subsequently maps documents retrieved
    via the streams interface or .next()

    Parameters:

    Returns:

    Example

    1. // Map documents returned by `data` events
    2. Thing.
    3.   find({ name: /^hello/ }).
    4.   cursor().
    5.   map(function (doc) {
    6.    doc.foo = "bar";
    7.    return doc;
    8.   })
    9.   on('data', function(doc) { console.log(doc.foo); });
    11. // Or map documents returned by `.next()`
    12. var cursor = Thing.find({ name: /^hello/ }).
    13.   cursor().
    14.   map(function (doc) {
    15.     doc.foo = "bar";
    16.     return doc;
    17.   });
    18. cursor.next(function(error, doc) {
    19.   console.log(doc.foo);
    20. });

    AggregationCursor#next(callback)

    Get the next document from this cursor. Will return null when there are
    no documents left.

    Parameters:

    Returns:

  • schema/boolean.js

    SchemaBoolean#cast(value, model)

    Casts to boolean

    Parameters:

    show code

    1. SchemaBoolean.prototype.cast = function(value, model) {
    2.   if (value === null) {
    3.     return value;
    4.   }
    6.   if (this.options.strictBool || (model && model.schema.options.strictBool && this.options.strictBool !== false)) {
    7.     // strict mode (throws if value is not a boolean, instead of converting)
    8.     if (value === true || value === 'true' || value === 1 || value === '1') {
    9.       return true;
    10.     }
    11.     if (value === false || value === 'false' || value === 0 || value === '0') {
    12.       return false;
    13.     }
    14.     throw new CastError('boolean', value, this.path);
    15.   } else {
    16.     // legacy mode
    17.     if (value === '0') {
    18.       return false;
    19.     }
    20.     if (value === 'true') {
    21.       return true;
    22.     }
    23.     if (value === 'false') {
    24.       return false;
    25.     }
    26.     return !!value;
    27.   }
    28. };
    30. SchemaBoolean.$conditionalHandlers =
    31.     utils.options(SchemaType.prototype.$conditionalHandlers, {});

    SchemaBoolean#castForQuery($conditional, val)

    Casts contents for queries.

    Parameters:

    show code

    1. SchemaBoolean.prototype.castForQuery = function($conditional, val) {
    2.   var handler;
    3.   if (arguments.length === 2) {
    4.     handler = SchemaBoolean.$conditionalHandlers[$conditional];
    6.     if (handler) {
    7.       return handler.call(this, val);
    8.     }
    10.     return this._castForQuery(val);
    11.   }
    13.   return this._castForQuery($conditional);
    14. };

    SchemaBoolean#checkRequired(value)

    Check if the given value satisfies a required validator. For a boolean
    to satisfy a required validator, it must be strictly equal to true or to
    false.

    Parameters:

    Returns:

    show code

    1. SchemaBoolean.prototype.checkRequired = function(value) {
    2.   return value === true || value === false;
    3. };

    SchemaBoolean(path, options)

    Boolean SchemaType constructor.

    Parameters:

    Inherits:

    show code

    1. function SchemaBoolean(path, options) {
    2.   SchemaType.call(this, path, options, 'Boolean');
    3. }

    SchemaBoolean.schemaName

    This schema type’s name, to defend against minifiers that mangle
    function names.

    show code

    1. SchemaBoolean.schemaName = 'Boolean';

  • schema/documentarray.js

    DocumentArray#cast(value, document)

    Casts contents

    Parameters:

    show code

    1. DocumentArray.prototype.cast = function(value, doc, init, prev, options) {
    2.   // lazy load
    3.   MongooseDocumentArray || (MongooseDocumentArray = require('../types/documentarray'));
    5.   var selected;
    6.   var subdoc;
    7.   var i;
    8.   var _opts = { transform: false, virtuals: false };
    10.   if (!Array.isArray(value)) {
    11.     // gh-2442 mark whole array as modified if we're initializing a doc from
    12.     // the db and the path isn't an array in the document
    13.     if (!!doc && init) {
    14.       doc.markModified(this.path);
    15.     }
    16.     return this.cast([value], doc, init, prev);
    17.   }
    19.   if (!(value && value.isMongooseDocumentArray) &&
    20.       (!options || !options.skipDocumentArrayCast)) {
    21.     value = new MongooseDocumentArray(value, this.path, doc);
    22.     if (prev && prev._handlers) {
    23.       for (var key in prev._handlers) {
    24.         doc.removeListener(key, prev._handlers[key]);
    25.       }
    26.     }
    27.   } else if (value && value.isMongooseDocumentArray) {
    28.     // We need to create a new array, otherwise change tracking will
    29.     // update the old doc (gh-4449)
    30.     value = new MongooseDocumentArray(value, this.path, doc);
    31.   }
    33.   i = value.length;
    35.   while (i--) {
    36.     if (!value[i]) {
    37.       continue;
    38.     }
    40.     var Constructor = this.casterConstructor;
    41.     if (Constructor.discriminators &&
    42.         typeof value[i][Constructor.schema.options.discriminatorKey] === 'string' &&
    43.         Constructor.discriminators[value[i][Constructor.schema.options.discriminatorKey]]) {
    44.       Constructor = Constructor.discriminators[value[i][Constructor.schema.options.discriminatorKey]];
    45.     }
    47.     // Check if the document has a different schema (re gh-3701)
    48.     if ((value[i] instanceof Document) &&
    49.         value[i].schema !== Constructor.schema) {
    50.       value[i] = value[i].toObject({ transform: false, virtuals: false });
    51.     }
    52.     if (!(value[i] instanceof Subdocument) && value[i]) {
    53.       if (init) {
    54.         if (doc) {
    55.           selected || (selected = scopePaths(this, doc.$__.selected, init));
    56.         } else {
    57.           selected = true;
    58.         }
    60.         subdoc = new Constructor(null, value, true, selected, i);
    61.         value[i] = subdoc.init(value[i]);
    62.       } else {
    63.         if (prev && (subdoc = prev.id(value[i]._id))) {
    64.           subdoc = prev.id(value[i]._id);
    65.         }
    67.         if (prev && subdoc && utils.deepEqual(subdoc.toObject(_opts), value[i])) {
    68.           // handle resetting doc with existing id and same data
    69.           subdoc.set(value[i]);
    70.           // if set() is hooked it will have no return value
    71.           // see gh-746
    72.           value[i] = subdoc;
    73.         } else {
    74.           try {
    75.             subdoc = new Constructor(value[i], value, undefined,
    76.                 undefined, i);
    77.             // if set() is hooked it will have no return value
    78.             // see gh-746
    79.             value[i] = subdoc;
    80.           } catch (error) {
    81.             var valueInErrorMessage = util.inspect(value[i]);
    82.             throw new CastError('embedded', valueInErrorMessage,
    83.               value._path, error);
    84.           }
    85.         }
    86.       }
    87.     }
    88.   }
    90.   return value;
    91. };

    DocumentArray(key, schema, options)

    SubdocsArray SchemaType constructor

    Parameters:

    Inherits:

    show code

    1. function DocumentArray(key, schema, options) {
    2.   var EmbeddedDocument = _createConstructor(schema, options);
    3.   EmbeddedDocument.prototype.$basePath = key;
    5.   ArrayType.call(this, key, EmbeddedDocument, options);
    7.   this.schema = schema;
    8.   this.$isMongooseDocumentArray = true;
    9.   var fn = this.defaultValue;
    11.   if (!('defaultValue' in this) || fn !== void 0) {
    12.     this.default(function() {
    13.       var arr = fn.call(this);
    14.       if (!Array.isArray(arr)) {
    15.         arr = [arr];
    16.       }
    17.       // Leave it up to `cast()` to convert this to a documentarray
    18.       return arr;
    19.     });
    20.   }
    21. }

    DocumentArray#doValidate()

    Performs local validations first, then validations on each embedded doc

    show code

    1. DocumentArray.prototype.doValidate = function(array, fn, scope, options) {
    2.   // lazy load
    3.   MongooseDocumentArray || (MongooseDocumentArray = require('../types/documentarray'));
    5.   var _this = this;
    6.   SchemaType.prototype.doValidate.call(this, array, function(err) {
    7.     if (err) {
    8.       return fn(err);
    9.     }
    11.     var count = array && array.length;
    12.     var error;
    14.     if (!count) {
    15.       return fn();
    16.     }
    17.     if (options && options.updateValidator) {
    18.       return fn();
    19.     }
    20.     if (!array.isMongooseDocumentArray) {
    21.       array = new MongooseDocumentArray(array, _this.path, scope);
    22.     }
    24.     // handle sparse arrays, do not use array.forEach which does not
    25.     // iterate over sparse elements yet reports array.length including
    26.     // them :(
    28.     function callback(err) {
    29.       if (err) {
    30.         error = err;
    31.       }
    32.       --count || fn(error);
    33.     }
    35.     for (var i = 0, len = count; i < len; ++i) {
    36.       // sidestep sparse entries
    37.       var doc = array[i];
    38.       if (!doc) {
    39.         --count || fn(error);
    40.         continue;
    41.       }
    43.       // If you set the array index directly, the doc might not yet be
    44.       // a full fledged mongoose subdoc, so make it into one.
    45.       if (!(doc instanceof Subdocument)) {
    46.         doc = array[i] = new _this.casterConstructor(doc, array, undefined,
    47.             undefined, i);
    48.       }
    50.       // HACK: use $__original_validate to avoid promises so bluebird doesn't
    51.       // complain
    52.       if (doc.$__original_validate) {
    53.         doc.$__original_validate({__noPromise: true}, callback);
    54.       } else {
    55.         doc.validate({__noPromise: true}, callback);
    56.       }
    57.     }
    58.   }, scope);
    59. };

    DocumentArray#doValidateSync()

    Performs local validations first, then validations on each embedded doc.

    Returns:

    Note:

    This method ignores the asynchronous validators.

    show code

    1. DocumentArray.prototype.doValidateSync = function(array, scope) {
    2.   var schemaTypeError = SchemaType.prototype.doValidateSync.call(this, array, scope);
    3.   if (schemaTypeError) {
    4.     return schemaTypeError;
    5.   }
    7.   var count = array && array.length,
    8.       resultError = null;
    10.   if (!count) {
    11.     return;
    12.   }
    14.   // handle sparse arrays, do not use array.forEach which does not
    15.   // iterate over sparse elements yet reports array.length including
    16.   // them :(
    18.   for (var i = 0, len = count; i < len; ++i) {
    19.     // only first error
    20.     if (resultError) {
    21.       break;
    22.     }
    23.     // sidestep sparse entries
    24.     var doc = array[i];
    25.     if (!doc) {
    26.       continue;
    27.     }
    29.     // If you set the array index directly, the doc might not yet be
    30.     // a full fledged mongoose subdoc, so make it into one.
    31.     if (!(doc instanceof Subdocument)) {
    32.       doc = array[i] = new this.casterConstructor(doc, array, undefined,
    33.         undefined, i);
    34.     }
    36.     var subdocValidateError = doc.validateSync();
    38.     if (subdocValidateError) {
    39.       resultError = subdocValidateError;
    40.     }
    41.   }
    43.   return resultError;
    44. };

    DocumentArray.schemaName

    This schema type’s name, to defend against minifiers that mangle
    function names.

    show code

    1. DocumentArray.schemaName = 'DocumentArray';

  • schema/array.js

    SchemaArray#applyGetters(value, scope)

    Overrides the getters application for the population special-case

    Parameters:

    show code

    1. SchemaArray.prototype.applyGetters = function(value, scope) {
    2.   if (this.caster.options && this.caster.options.ref) {
    3.     // means the object id was populated
    4.     return value;
    5.   }
    7.   return SchemaType.prototype.applyGetters.call(this, value, scope);
    8. };

    SchemaArray#cast(value, doc, init)

    Casts values for set().

    Parameters:

    • value <Object>
    • doc <Document> document that triggers the casting
    • init <Boolean> whether this is an initialization cast

    show code

    1. SchemaArray.prototype.cast = function(value, doc, init) {
    2.   // lazy load
    3.   MongooseArray || (MongooseArray = require('../types').Array);
    5.   if (Array.isArray(value)) {
    6.     if (!value.length && doc) {
    7.       var indexes = doc.schema.indexedPaths();
    9.       for (var i = 0, l = indexes.length; i < l; ++i) {
    10.         var pathIndex = indexes[i][0][this.path];
    11.         if (pathIndex === '2dsphere' || pathIndex === '2d') {
    12.           return;
    13.         }
    14.       }
    15.     }
    17.     if (!(value && value.isMongooseArray)) {
    18.       value = new MongooseArray(value, this.path, doc);
    19.     } else if (value && value.isMongooseArray) {
    20.       // We need to create a new array, otherwise change tracking will
    21.       // update the old doc (gh-4449)
    22.       value = new MongooseArray(value, this.path, doc);
    23.     }
    25.     if (this.caster) {
    26.       try {
    27.         for (i = 0, l = value.length; i < l; i++) {
    28.           value[i] = this.caster.cast(value[i], doc, init);
    29.         }
    30.       } catch (e) {
    31.         // rethrow
    32.         throw new CastError('[' + e.kind + ']', util.inspect(value), this.path, e);
    33.       }
    34.     }
    36.     return value;
    37.   }
    38.   // gh-2442: if we're loading this from the db and its not an array, mark
    39.   // the whole array as modified.
    40.   if (!!doc && !!init) {
    41.     doc.markModified(this.path);
    42.   }
    43.   return this.cast([value], doc, init);
    44. };

    SchemaArray#castForQuery($conditional, [value])

    Casts values for queries.

    Parameters:

    • $conditional <String>
    • [value] <T>

    show code

    1. SchemaArray.prototype.castForQuery = function($conditional, value) {
    2.   var handler,
    3.       val;
    5.   if (arguments.length === 2) {
    6.     handler = this.$conditionalHandlers[$conditional];
    8.     if (!handler) {
    9.       throw new Error('Can\'t use ' + $conditional + ' with Array.');
    10.     }
    12.     val = handler.call(this, value);
    13.   } else {
    14.     val = $conditional;
    15.     var Constructor = this.casterConstructor;
    17.     if (val &&
    18.         Constructor.discriminators &&
    19.         Constructor.schema.options.discriminatorKey &&
    20.         typeof val[Constructor.schema.options.discriminatorKey] === 'string' &&
    21.         Constructor.discriminators[val[Constructor.schema.options.discriminatorKey]]) {
    22.       Constructor = Constructor.discriminators[val[Constructor.schema.options.discriminatorKey]];
    23.     }
    25.     var proto = this.casterConstructor.prototype;
    26.     var method = proto && (proto.castForQuery || proto.cast);
    27.     if (!method && Constructor.castForQuery) {
    28.       method = Constructor.castForQuery;
    29.     }
    30.     var caster = this.caster;
    32.     if (Array.isArray(val)) {
    33.       val = val.map(function(v) {
    34.         if (utils.isObject(v) && v.$elemMatch) {
    35.           return v;
    36.         }
    37.         if (method) {
    38.           v = method.call(caster, v);
    39.           return v;
    40.         }
    41.         if (v != null) {
    42.           v = new Constructor(v);
    43.           return v;
    44.         }
    45.         return v;
    46.       });
    47.     } else if (method) {
    48.       val = method.call(caster, val);
    49.     } else if (val != null) {
    50.       val = new Constructor(val);
    51.     }
    52.   }
    54.   return val;
    55. };
    57. function cast$all(val) {
    58.   if (!Array.isArray(val)) {
    59.     val = [val];
    60.   }
    62.   val = val.map(function(v) {
    63.     if (utils.isObject(v)) {
    64.       var o = {};
    65.       o[this.path] = v;
    66.       return cast(this.casterConstructor.schema, o)[this.path];
    67.     }
    68.     return v;
    69.   }, this);
    71.   return this.castForQuery(val);
    72. }
    74. function cast$elemMatch(val) {
    75.   var keys = Object.keys(val);
    76.   var numKeys = keys.length;
    77.   var key;
    78.   var value;
    79.   for (var i = 0; i < numKeys; ++i) {
    80.     key = keys[i];
    81.     value = val[key];
    82.     if (key.indexOf('$') === 0 && value) {
    83.       val[key] = this.castForQuery(key, value);
    84.     }
    85.   }
    87.   return cast(this.casterConstructor.schema, val);
    88. }
    90. var handle = SchemaArray.prototype.$conditionalHandlers = {};
    92. handle.$all = cast$all;
    93. handle.$options = String;
    94. handle.$elemMatch = cast$elemMatch;
    95. handle.$geoIntersects = geospatial.cast$geoIntersects;
    96. handle.$or = handle.$and = function(val) {
    97.   if (!Array.isArray(val)) {
    98.     throw new TypeError('conditional $or/$and require array');
    99.   }
    101.   var ret = [];
    102.   for (var i = 0; i < val.length; ++i) {
    103.     ret.push(cast(this.casterConstructor.schema, val[i]));
    104.   }
    106.   return ret;
    107. };
    109. handle.$near =
    110. handle.$nearSphere = geospatial.cast$near;
    112. handle.$within =
    113. handle.$geoWithin = geospatial.cast$within;
    115. handle.$size =
    116. handle.$minDistance =
    117. handle.$maxDistance = castToNumber;
    119. handle.$exists = $exists;
    120. handle.$type = $type;
    122. handle.$eq =
    123. handle.$gt =
    124. handle.$gte =
    125. handle.$in =
    126. handle.$lt =
    127. handle.$lte =
    128. handle.$ne =
    129. handle.$nin =
    130. handle.$regex = SchemaArray.prototype.castForQuery;

    SchemaArray#checkRequired(value)

    Check if the given value satisfies a required validator. The given value
    must be not null nor undefined, and have a positive length.

    Parameters:

    Returns:

    show code

    1. SchemaArray.prototype.checkRequired = function(value) {
    2.   return !!(value && value.length);
    3. };

    SchemaArray(key, cast, options)

    Array SchemaType constructor

    Parameters:

    Inherits:

    show code

    1. function SchemaArray(key, cast, options, schemaOptions) {
    2.   // lazy load
    3.   EmbeddedDoc || (EmbeddedDoc = require('../types').Embedded);
    5.   var typeKey = 'type';
    6.   if (schemaOptions && schemaOptions.typeKey) {
    7.     typeKey = schemaOptions.typeKey;
    8.   }
    10.   if (cast) {
    11.     var castOptions = {};
    13.     if (utils.getFunctionName(cast.constructor) === 'Object') {
    14.       if (cast[typeKey]) {
    15.         // support { type: Woot }
    16.         castOptions = utils.clone(cast); // do not alter user arguments
    17.         delete castOptions[typeKey];
    18.         cast = cast[typeKey];
    19.       } else {
    20.         cast = Mixed;
    21.       }
    22.     }
    24.     // support { type: 'String' }
    25.     var name = typeof cast === 'string'
    26.         ? cast
    27.         : utils.getFunctionName(cast);
    29.     var caster = name in Types
    30.         ? Types[name]
    31.         : cast;
    33.     this.casterConstructor = caster;
    34.     if (typeof caster === 'function' && !caster.$isArraySubdocument) {
    35.       this.caster = new caster(null, castOptions);
    36.     } else {
    37.       this.caster = caster;
    38.     }
    40.     if (!(this.caster instanceof EmbeddedDoc)) {
    41.       this.caster.path = key;
    42.     }
    43.   }
    45.   this.$isMongooseArray = true;
    47.   SchemaType.call(this, key, options, 'Array');
    49.   var defaultArr;
    50.   var fn;
    52.   if (this.defaultValue != null) {
    53.     defaultArr = this.defaultValue;
    54.     fn = typeof defaultArr === 'function';
    55.   }
    57.   if (!('defaultValue' in this) || this.defaultValue !== void 0) {
    58.     this.default(function() {
    59.       var arr = [];
    60.       if (fn) {
    61.         arr = defaultArr();
    62.       } else if (defaultArr != null) {
    63.         arr = arr.concat(defaultArr);
    64.       }
    65.       // Leave it up to `cast()` to convert the array
    66.       return arr;
    67.     });
    68.   }
    69. }

    SchemaArray.schemaName

    This schema type’s name, to defend against minifiers that mangle
    function names.

    show code

    1. SchemaArray.schemaName = 'Array';

  • schema/decimal128.js

    Decimal128#cast(value, doc, init)

    Casts to Decimal128

    Parameters:

    show code

    1. Decimal128.prototype.cast = function(value, doc, init) {
    2.   if (SchemaType._isRef(this, value, doc, init)) {
    3.     // wait! we may need to cast this to a document
    5.     if (value === null || value === undefined) {
    6.       return value;
    7.     }
    9.     // lazy load
    10.     Document || (Document = require('./../document'));
    12.     if (value instanceof Document) {
    13.       value.$__.wasPopulated = true;
    14.       return value;
    15.     }
    17.     // setting a populated path
    18.     if (value instanceof Decimal128Type) {
    19.       return value;
    20.     } else if (Buffer.isBuffer(value) || !utils.isObject(value)) {
    21.       throw new CastError('Decimal128', value, this.path);
    22.     }
    24.     // Handle the case where user directly sets a populated
    25.     // path to a plain object; cast to the Model used in
    26.     // the population query.
    27.     var path = doc.$__fullPath(this.path);
    28.     var owner = doc.ownerDocument ? doc.ownerDocument() : doc;
    29.     var pop = owner.populated(path, true);
    30.     var ret = value;
    31.     if (!doc.$__.populated ||
    32.         !doc.$__.populated[path] ||
    33.         !doc.$__.populated[path].options ||
    34.         !doc.$__.populated[path].options.options ||
    35.         !doc.$__.populated[path].options.options.lean) {
    36.       ret = new pop.options.model(value);
    37.       ret.$__.wasPopulated = true;
    38.     }
    40.     return ret;
    41.   }
    43.   if (value == null) {
    44.     return value;
    45.   }
    47.   if (typeof value === 'object' && typeof value.$numberDecimal === 'string') {
    48.     return Decimal128Type.fromString(value.$numberDecimal);
    49.   }
    51.   if (value instanceof Decimal128Type) {
    52.     return value;
    53.   }
    55.   if (typeof value === 'string') {
    56.     return Decimal128Type.fromString(value);
    57.   }
    59.   if (Buffer.isBuffer(value)) {
    60.     return new Decimal128Type(value);
    61.   }
    63.   throw new CastError('Decimal128', value, this.path);
    64. };

    Decimal128#checkRequired(value, doc)

    Check if the given value satisfies a required validator.

    Parameters:

    Returns:

    show code

    1. Decimal128.prototype.checkRequired = function checkRequired(value, doc) {
    2.   if (SchemaType._isRef(this, value, doc, true)) {
    3.     return !!value;
    4.   }
    5.   return value instanceof Decimal128Type;
    6. };

    Decimal128(key, options)

    Decimal128 SchemaType constructor.

    Parameters:

    Inherits:

    show code

    1. function Decimal128(key, options) {
    2.   SchemaType.call(this, key, options, 'Decimal128');
    3. }

    Decimal128.schemaName

    This schema type’s name, to defend against minifiers that mangle
    function names.

    show code

    1. Decimal128.schemaName = 'Decimal128';

  • schema/number.js

    SchemaNumber#cast(value, doc, init)

    Casts to number

    Parameters:

    show code

    1. SchemaNumber.prototype.cast = function(value, doc, init) {
    2.   if (SchemaType._isRef(this, value, doc, init)) {
    3.     // wait! we may need to cast this to a document
    5.     if (value === null || value === undefined) {
    6.       return value;
    7.     }
    9.     // lazy load
    10.     Document || (Document = require('./../document'));
    12.     if (value instanceof Document) {
    13.       value.$__.wasPopulated = true;
    14.       return value;
    15.     }
    17.     // setting a populated path
    18.     if (typeof value === 'number') {
    19.       return value;
    20.     } else if (Buffer.isBuffer(value) || !utils.isObject(value)) {
    21.       throw new CastError('number', value, this.path);
    22.     }
    24.     // Handle the case where user directly sets a populated
    25.     // path to a plain object; cast to the Model used in
    26.     // the population query.
    27.     var path = doc.$__fullPath(this.path);
    28.     var owner = doc.ownerDocument ? doc.ownerDocument() : doc;
    29.     var pop = owner.populated(path, true);
    30.     var ret = new pop.options.model(value);
    31.     ret.$__.wasPopulated = true;
    32.     return ret;
    33.   }
    35.   var val = value && typeof value._id !== 'undefined' ?
    36.     value._id : // documents
    37.     value;
    39.   if (!isNaN(val)) {
    40.     if (val === null) {
    41.       return val;
    42.     }
    43.     if (val === '') {
    44.       return null;
    45.     }
    46.     if (typeof val === 'string' || typeof val === 'boolean') {
    47.       val = Number(val);
    48.     }
    49.     if (val instanceof Number) {
    50.       return val;
    51.     }
    52.     if (typeof val === 'number') {
    53.       return val;
    54.     }
    55.     if (val.toString && !Array.isArray(val) && val.toString() == Number(val)) {
    56.       return new Number(val);
    57.     }
    58.   }
    60.   throw new CastError('number', value, this.path);
    61. };

    SchemaNumber#castForQuery($conditional, [value])

    Casts contents for queries.

    Parameters:

    • $conditional <String>
    • [value] <T>

    show code

    1. SchemaNumber.prototype.castForQuery = function($conditional, val) {
    2.   var handler;
    3.   if (arguments.length === 2) {
    4.     handler = this.$conditionalHandlers[$conditional];
    5.     if (!handler) {
    6.       throw new Error('Can\'t use ' + $conditional + ' with Number.');
    7.     }
    8.     return handler.call(this, val);
    9.   }
    10.   val = this._castForQuery($conditional);
    11.   return val;
    12. };

    SchemaNumber#checkRequired(value, doc)

    Check if the given value satisfies a required validator.

    Parameters:

    Returns:

    show code

    1. SchemaNumber.prototype.checkRequired = function checkRequired(value, doc) {
    2.   if (SchemaType._isRef(this, value, doc, true)) {
    3.     return !!value;
    4.   }
    5.   return typeof value === 'number' || value instanceof Number;
    6. };

    SchemaNumber#max(maximum, [message])

    Sets a maximum number validator.

    Parameters:

    • maximum <Number> number
    • [message] <String> optional custom error message

    Returns:

    See:

    Example:

    1. var s = new Schema({ n: { type: Number, max: 10 })
    2. var M = db.model('M', s)
    3. var m = new M({ n: 11 })
    4. m.save(function (err) {
    5.   console.error(err) // validator error
    6.   m.n = 10;
    7.   m.save() // success
    8. })
    10. // custom error messages
    11. // We can also use the special {MAX} token which will be replaced with the invalid value
    12. var max = [10, 'The value of path `{PATH}` ({VALUE}) exceeds the limit ({MAX}).'];
    13. var schema = new Schema({ n: { type: Number, max: max })
    14. var M = mongoose.model('Measurement', schema);
    15. var s= new M({ n: 4 });
    16. s.validate(function (err) {
    17.   console.log(String(err)) // ValidationError: The value of path `n` (4) exceeds the limit (10).
    18. })

    show code

    1. SchemaNumber.prototype.max = function(value, message) {
    2.   if (this.maxValidator) {
    3.     this.validators = this.validators.filter(function(v) {
    4.       return v.validator !== this.maxValidator;
    5.     }, this);
    6.   }
    8.   if (value !== null && value !== undefined) {
    9.     var msg = message || MongooseError.messages.Number.max;
    10.     msg = msg.replace(/{MAX}/, value);
    11.     this.validators.push({
    12.       validator: this.maxValidator = function(v) {
    13.         return v == null || v <= value;
    14.       },
    15.       message: msg,
    16.       type: 'max',
    17.       max: value
    18.     });
    19.   }
    21.   return this;
    22. };

    SchemaNumber#min(value, [message])

    Sets a minimum number validator.

    Parameters:

    • value <Number> minimum number
    • [message] <String> optional custom error message

    Returns:

    See:

    Example:

    1. var s = new Schema({ n: { type: Number, min: 10 })
    2. var M = db.model('M', s)
    3. var m = new M({ n: 9 })
    4. m.save(function (err) {
    5.   console.error(err) // validator error
    6.   m.n = 10;
    7.   m.save() // success
    8. })
    10. // custom error messages
    11. // We can also use the special {MIN} token which will be replaced with the invalid value
    12. var min = [10, 'The value of path `{PATH}` ({VALUE}) is beneath the limit ({MIN}).'];
    13. var schema = new Schema({ n: { type: Number, min: min })
    14. var M = mongoose.model('Measurement', schema);
    15. var s= new M({ n: 4 });
    16. s.validate(function (err) {
    17.   console.log(String(err)) // ValidationError: The value of path `n` (4) is beneath the limit (10).
    18. })

    show code

    1. SchemaNumber.prototype.min = function(value, message) {
    2.   if (this.minValidator) {
    3.     this.validators = this.validators.filter(function(v) {
    4.       return v.validator !== this.minValidator;
    5.     }, this);
    6.   }
    8.   if (value !== null && value !== undefined) {
    9.     var msg = message || MongooseError.messages.Number.min;
    10.     msg = msg.replace(/{MIN}/, value);
    11.     this.validators.push({
    12.       validator: this.minValidator = function(v) {
    13.         return v == null || v >= value;
    14.       },
    15.       message: msg,
    16.       type: 'min',
    17.       min: value
    18.     });
    19.   }
    21.   return this;
    22. };

    SchemaNumber(key, options)

    Number SchemaType constructor.

    Parameters:

    Inherits:

    show code

    1. function SchemaNumber(key, options) {
    2.   SchemaType.call(this, key, options, 'Number');
    3. }

    SchemaNumber.schemaName

    This schema type’s name, to defend against minifiers that mangle
    function names.

    show code

    1. SchemaNumber.schemaName = 'Number';

  • schema/objectid.js

    ObjectId#auto(turnOn)

    Adds an auto-generated ObjectId default if turnOn is true.

    Parameters:

    • turnOn <Boolean> auto generated ObjectId defaults

    Returns:

    show code

    1. ObjectId.prototype.auto = function(turnOn) {
    2.   if (turnOn) {
    3.     this.default(defaultId);
    4.     this.set(resetId);
    5.   }
    7.   return this;
    8. };

    ObjectId#cast(value, doc, init)

    Casts to ObjectId

    Parameters:

    show code

    1. ObjectId.prototype.cast = function(value, doc, init) {
    2.   if (SchemaType._isRef(this, value, doc, init)) {
    3.     // wait! we may need to cast this to a document
    5.     if (value === null || value === undefined) {
    6.       return value;
    7.     }
    9.     // lazy load
    10.     Document || (Document = require('./../document'));
    12.     if (value instanceof Document) {
    13.       value.$__.wasPopulated = true;
    14.       return value;
    15.     }
    17.     // setting a populated path
    18.     if (value instanceof oid) {
    19.       return value;
    20.     } else if ((value.constructor.name || '').toLowerCase() === 'objectid') {
    21.       return new oid(value.toHexString());
    22.     } else if (Buffer.isBuffer(value) || !utils.isObject(value)) {
    23.       throw new CastError('ObjectId', value, this.path);
    24.     }
    26.     // Handle the case where user directly sets a populated
    27.     // path to a plain object; cast to the Model used in
    28.     // the population query.
    29.     var path = doc.$__fullPath(this.path);
    30.     var owner = doc.ownerDocument ? doc.ownerDocument() : doc;
    31.     var pop = owner.populated(path, true);
    32.     var ret = value;
    33.     if (!doc.$__.populated ||
    34.         !doc.$__.populated[path] ||
    35.         !doc.$__.populated[path].options ||
    36.         !doc.$__.populated[path].options.options ||
    37.         !doc.$__.populated[path].options.options.lean) {
    38.       ret = new pop.options.model(value);
    39.       ret.$__.wasPopulated = true;
    40.     }
    42.     return ret;
    43.   }
    45.   if (value === null || value === undefined) {
    46.     return value;
    47.   }
    49.   if (value instanceof oid) {
    50.     return value;
    51.   }
    53.   if (value._id) {
    54.     if (value._id instanceof oid) {
    55.       return value._id;
    56.     }
    57.     if (value._id.toString instanceof Function) {
    58.       try {
    59.         return new oid(value._id.toString());
    60.       } catch (e) {
    61.       }
    62.     }
    63.   }
    65.   if (value.toString instanceof Function) {
    66.     try {
    67.       return new oid(value.toString());
    68.     } catch (err) {
    69.       throw new CastError('ObjectId', value, this.path);
    70.     }
    71.   }
    73.   throw new CastError('ObjectId', value, this.path);
    74. };

    ObjectId#castForQuery($conditional, [val])

    Casts contents for queries.

    Parameters:

    • $conditional <String>
    • [val] <T>

    show code

    1. ObjectId.prototype.castForQuery = function($conditional, val) {
    2.   var handler;
    3.   if (arguments.length === 2) {
    4.     handler = this.$conditionalHandlers[$conditional];
    5.     if (!handler) {
    6.       throw new Error('Can\'t use ' + $conditional + ' with ObjectId.');
    7.     }
    8.     return handler.call(this, val);
    9.   }
    10.   return this._castForQuery($conditional);
    11. };

    ObjectId#checkRequired(value, doc)

    Check if the given value satisfies a required validator.

    Parameters:

    Returns:

    show code

    1. ObjectId.prototype.checkRequired = function checkRequired(value, doc) {
    2.   if (SchemaType._isRef(this, value, doc, true)) {
    3.     return !!value;
    4.   }
    5.   return value instanceof oid;
    6. };

    ObjectId(key, options)

    ObjectId SchemaType constructor.

    Parameters:

    Inherits:

    show code

    1. function ObjectId(key, options) {
    2.   var isKeyHexStr = typeof key === 'string' && key.length === 24 && /^a-f0-9$/i.test(key);
    3.   var suppressWarning = options && options.suppressWarning;
    4.   if ((isKeyHexStr || typeof key === 'undefined') && !suppressWarning) {
    5.     console.warn('mongoose: To create a new ObjectId please try ' +
    6.       '`Mongoose.Types.ObjectId` instead of using ' +
    7.       '`Mongoose.Schema.ObjectId`. Set the `suppressWarning` option if ' +
    8.       'you\'re trying to create a hex char path in your schema.');
    9.     console.trace();
    10.   }
    11.   SchemaType.call(this, key, options, 'ObjectID');
    12. }

    ObjectId.schemaName

    This schema type’s name, to defend against minifiers that mangle
    function names.

    show code

    1. ObjectId.schemaName = 'ObjectId';

  • schema/string.js

    SchemaString#cast()

    Casts to String

    show code

    1. SchemaString.prototype.cast = function(value, doc, init) {
    2.   if (SchemaType._isRef(this, value, doc, init)) {
    3.     // wait! we may need to cast this to a document
    5.     if (value === null || value === undefined) {
    6.       return value;
    7.     }
    9.     // lazy load
    10.     Document || (Document = require('./../document'));
    12.     if (value instanceof Document) {
    13.       value.$__.wasPopulated = true;
    14.       return value;
    15.     }
    17.     // setting a populated path
    18.     if (typeof value === 'string') {
    19.       return value;
    20.     } else if (Buffer.isBuffer(value) || !utils.isObject(value)) {
    21.       throw new CastError('string', value, this.path);
    22.     }
    24.     // Handle the case where user directly sets a populated
    25.     // path to a plain object; cast to the Model used in
    26.     // the population query.
    27.     var path = doc.$__fullPath(this.path);
    28.     var owner = doc.ownerDocument ? doc.ownerDocument() : doc;
    29.     var pop = owner.populated(path, true);
    30.     var ret = new pop.options.model(value);
    31.     ret.$__.wasPopulated = true;
    32.     return ret;
    33.   }
    35.   // If null or undefined
    36.   if (value === null || value === undefined) {
    37.     return value;
    38.   }
    40.   if (typeof value !== 'undefined') {
    41.     // handle documents being passed
    42.     if (value._id && typeof value._id === 'string') {
    43.       return value._id;
    44.     }
    46.     // Re: gh-647 and gh-3030, we're ok with casting using `toString()`
    47.     // **unless** its the default Object.toString, because "[object Object]"
    48.     // doesn't really qualify as useful data
    49.     if (value.toString && value.toString !== Object.prototype.toString) {
    50.       return value.toString();
    51.     }
    52.   }
    54.   throw new CastError('string', value, this.path);
    55. };

    SchemaString#castForQuery($conditional, [val])

    Casts contents for queries.

    Parameters:

    • $conditional <String>
    • [val] <T>

    show code

    1. SchemaString.prototype.castForQuery = function($conditional, val) {
    2.   var handler;
    3.   if (arguments.length === 2) {
    4.     handler = this.$conditionalHandlers[$conditional];
    5.     if (!handler) {
    6.       throw new Error('Can\'t use ' + $conditional + ' with String.');
    7.     }
    8.     return handler.call(this, val);
    9.   }
    10.   val = $conditional;
    11.   if (Object.prototype.toString.call(val) === '[object RegExp]') {
    12.     return val;
    13.   }
    15.   return this._castForQuery(val);
    16. };

    SchemaString#checkRequired(value, doc)

    Check if the given value satisfies the required validator. The value is
    considered valid if it is a string (that is, not null or undefined) and
    has positive length. The required validator will fail for empty
    strings.

    Parameters:

    Returns:

    show code

    1. SchemaString.prototype.checkRequired = function checkRequired(value, doc) {
    2.   if (SchemaType._isRef(this, value, doc, true)) {
    3.     return !!value;
    4.   }
    5.   return (value instanceof String || typeof value === 'string') && value.length;
    6. };

    SchemaString#enum([args...])

    Adds an enum validator

    Parameters:

    Returns:

    See:

    Example:

    1. var states = ['opening', 'open', 'closing', 'closed']
    2. var s = new Schema({ state: { type: String, enum: states }})
    3. var M = db.model('M', s)
    4. var m = new M({ state: 'invalid' })
    5. m.save(function (err) {
    6.   console.error(String(err)) // ValidationError: `invalid` is not a valid enum value for path `state`.
    7.   m.state = 'open'
    8.   m.save(callback) // success
    9. })
    11. // or with custom error messages
    12. var enum = {
    13.   values: ['opening', 'open', 'closing', 'closed'],
    14.   message: 'enum validator failed for path `{PATH}` with value `{VALUE}`'
    15. }
    16. var s = new Schema({ state: { type: String, enum: enum })
    17. var M = db.model('M', s)
    18. var m = new M({ state: 'invalid' })
    19. m.save(function (err) {
    20.   console.error(String(err)) // ValidationError: enum validator failed for path `state` with value `invalid`
    21.   m.state = 'open'
    22.   m.save(callback) // success
    23. })

    show code

    1. SchemaString.prototype.enum = function() {
    2.   if (this.enumValidator) {
    3.     this.validators = this.validators.filter(function(v) {
    4.       return v.validator !== this.enumValidator;
    5.     }, this);
    6.     this.enumValidator = false;
    7.   }
    9.   if (arguments[0] === void 0 || arguments[0] === false) {
    10.     return this;
    11.   }
    13.   var values;
    14.   var errorMessage;
    16.   if (utils.isObject(arguments[0])) {
    17.     values = arguments[0].values;
    18.     errorMessage = arguments[0].message;
    19.   } else {
    20.     values = arguments;
    21.     errorMessage = MongooseError.messages.String.enum;
    22.   }
    24.   for (var i = 0; i < values.length; i++) {
    25.     if (undefined !== values[i]) {
    26.       this.enumValues.push(this.cast(values[i]));
    27.     }
    28.   }
    30.   var vals = this.enumValues;
    31.   this.enumValidator = function(v) {
    32.     return undefined === v || ~vals.indexOf(v);
    33.   };
    34.   this.validators.push({
    35.     validator: this.enumValidator,
    36.     message: errorMessage,
    37.     type: 'enum',
    38.     enumValues: vals
    39.   });
    41.   return this;
    42. };

    SchemaString#lowercase()

    Adds a lowercase setter.

    Returns:

    Example:

    1. var s = new Schema({ email: { type: String, lowercase: true }})
    2. var M = db.model('M', s);
    3. var m = new M({ email: 'SomeEmail@example.COM' });
    4. console.log(m.email) // someemail@example.com

    NOTE: Setters do not run on queries by default. Use the runSettersOnQuery option:

    1.  // Must use `runSettersOnQuery` as shown below, otherwise `email` will
    2.  // **not** be lowercased.
    3.  M.updateOne({}, { $set: { email: 'SomeEmail@example.COM' } }, { runSettersOnQuery: true });

    show code

    1. SchemaString.prototype.lowercase = function(shouldApply) {
    2.   if (arguments.length > 0 && !shouldApply) {
    3.     return this;
    4.   }
    5.   return this.set(function(v, self) {
    6.     if (typeof v !== 'string') {
    7.       v = self.cast(v);
    8.     }
    9.     if (v) {
    10.       return v.toLowerCase();
    11.     }
    12.     return v;
    13.   });
    14. };

    SchemaString#match(regExp, [message])

    Sets a regexp validator.

    Parameters:

    • regExp <RegExp> regular expression to test against
    • [message] <String> optional custom error message

    Returns:

    See:

    Any value that does not pass regExp.test(val) will fail validation.

    Example:

    1. var s = new Schema({ name: { type: String, match: /^a/ }})
    2. var M = db.model('M', s)
    3. var m = new M({ name: 'I am invalid' })
    4. m.validate(function (err) {
    5.   console.error(String(err)) // "ValidationError: Path `name` is invalid (I am invalid)."
    6.   m.name = 'apples'
    7.   m.validate(function (err) {
    8.     assert.ok(err) // success
    9.   })
    10. })
    12. // using a custom error message
    13. var match = [ /\.html$/, "That file doesn't end in .html ({VALUE})" ];
    14. var s = new Schema({ file: { type: String, match: match }})
    15. var M = db.model('M', s);
    16. var m = new M({ file: 'invalid' });
    17. m.validate(function (err) {
    18.   console.log(String(err)) // "ValidationError: That file doesn't end in .html (invalid)"
    19. })

    Empty strings, undefined, and null values always pass the match validator. If you require these values, enable the required validator also.

    1. var s = new Schema({ name: { type: String, match: /^a/, required: true }})

    show code

    1. SchemaString.prototype.match = function match(regExp, message) {
    2.   // yes, we allow multiple match validators
    4.   var msg = message || MongooseError.messages.String.match;
    6.   var matchValidator = function(v) {
    7.     if (!regExp) {
    8.       return false;
    9.     }
    11.     var ret = ((v != null && v !== '')
    12.         ? regExp.test(v)
    13.         : true);
    14.     return ret;
    15.   };
    17.   this.validators.push({
    18.     validator: matchValidator,
    19.     message: msg,
    20.     type: 'regexp',
    21.     regexp: regExp
    22.   });
    23.   return this;
    24. };

    SchemaString#maxlength(value, [message])

    Sets a maximum length validator.

    Parameters:

    • value <Number> maximum string length
    • [message] <String> optional custom error message

    Returns:

    See:

    Example:

    1. var schema = new Schema({ postalCode: { type: String, maxlength: 9 })
    2. var Address = db.model('Address', schema)
    3. var address = new Address({ postalCode: '9512512345' })
    4. address.save(function (err) {
    5.   console.error(err) // validator error
    6.   address.postalCode = '95125';
    7.   address.save() // success
    8. })
    10. // custom error messages
    11. // We can also use the special {MAXLENGTH} token which will be replaced with the maximum allowed length
    12. var maxlength = [9, 'The value of path `{PATH}` (`{VALUE}`) exceeds the maximum allowed length ({MAXLENGTH}).'];
    13. var schema = new Schema({ postalCode: { type: String, maxlength: maxlength })
    14. var Address = mongoose.model('Address', schema);
    15. var address = new Address({ postalCode: '9512512345' });
    16. address.validate(function (err) {
    17.   console.log(String(err)) // ValidationError: The value of path `postalCode` (`9512512345`) exceeds the maximum allowed length (9).
    18. })

    show code

    1. SchemaString.prototype.maxlength = function(value, message) {
    2.   if (this.maxlengthValidator) {
    3.     this.validators = this.validators.filter(function(v) {
    4.       return v.validator !== this.maxlengthValidator;
    5.     }, this);
    6.   }
    8.   if (value !== null && value !== undefined) {
    9.     var msg = message || MongooseError.messages.String.maxlength;
    10.     msg = msg.replace(/{MAXLENGTH}/, value);
    11.     this.validators.push({
    12.       validator: this.maxlengthValidator = function(v) {
    13.         return v === null || v.length <= value;
    14.       },
    15.       message: msg,
    16.       type: 'maxlength',
    17.       maxlength: value
    18.     });
    19.   }
    21.   return this;
    22. };

    SchemaString#minlength(value, [message])

    Sets a minimum length validator.

    Parameters:

    • value <Number> minimum string length
    • [message] <String> optional custom error message

    Returns:

    See:

    Example:

    1. var schema = new Schema({ postalCode: { type: String, minlength: 5 })
    2. var Address = db.model('Address', schema)
    3. var address = new Address({ postalCode: '9512' })
    4. address.save(function (err) {
    5.   console.error(err) // validator error
    6.   address.postalCode = '95125';
    7.   address.save() // success
    8. })
    10. // custom error messages
    11. // We can also use the special {MINLENGTH} token which will be replaced with the minimum allowed length
    12. var minlength = [5, 'The value of path `{PATH}` (`{VALUE}`) is shorter than the minimum allowed length ({MINLENGTH}).'];
    13. var schema = new Schema({ postalCode: { type: String, minlength: minlength })
    14. var Address = mongoose.model('Address', schema);
    15. var address = new Address({ postalCode: '9512' });
    16. address.validate(function (err) {
    17.   console.log(String(err)) // ValidationError: The value of path `postalCode` (`9512`) is shorter than the minimum length (5).
    18. })

    show code

    1. SchemaString.prototype.minlength = function(value, message) {
    2.   if (this.minlengthValidator) {
    3.     this.validators = this.validators.filter(function(v) {
    4.       return v.validator !== this.minlengthValidator;
    5.     }, this);
    6.   }
    8.   if (value !== null && value !== undefined) {
    9.     var msg = message || MongooseError.messages.String.minlength;
    10.     msg = msg.replace(/{MINLENGTH}/, value);
    11.     this.validators.push({
    12.       validator: this.minlengthValidator = function(v) {
    13.         return v === null || v.length >= value;
    14.       },
    15.       message: msg,
    16.       type: 'minlength',
    17.       minlength: value
    18.     });
    19.   }
    21.   return this;
    22. };

    SchemaString(key, options)

    String SchemaType constructor.

    Parameters:

    Inherits:

    show code

    1. function SchemaString(key, options) {
    2.   this.enumValues = [];
    3.   this.regExp = null;
    4.   SchemaType.call(this, key, options, 'String');
    5. }

    SchemaString#trim()

    Adds a trim setter.

    Returns:

    The string value will be trimmed when set.

    Example:

    1. var s = new Schema({ name: { type: String, trim: true }})
    2. var M = db.model('M', s)
    3. var string = ' some name '
    4. console.log(string.length) // 11
    5. var m = new M({ name: string })
    6. console.log(m.name.length) // 9

    NOTE: Setters do not run on queries by default. Use the runSettersOnQuery option:

    1.  // Must use `runSettersOnQuery` as shown below, otherwise `email` will
    2.  // **not** be lowercased.
    3.  M.updateOne({}, { $set: { email: 'SomeEmail@example.COM' } }, { runSettersOnQuery: true });

    show code

    1. SchemaString.prototype.trim = function(shouldTrim) {
    2.   if (arguments.length > 0 && !shouldTrim) {
    3.     return this;
    4.   }
    5.   return this.set(function(v, self) {
    6.     if (typeof v !== 'string') {
    7.       v = self.cast(v);
    8.     }
    9.     if (v) {
    10.       return v.trim();
    11.     }
    12.     return v;
    13.   });
    14. };

    SchemaString#uppercase()

    Adds an uppercase setter.

    Returns:

    Example:

    1. var s = new Schema({ caps: { type: String, uppercase: true }})
    2. var M = db.model('M', s);
    3. var m = new M({ caps: 'an example' });
    4. console.log(m.caps) // AN EXAMPLE

    NOTE: Setters do not run on queries by default. Use the runSettersOnQuery option:

    1.  // Must use `runSettersOnQuery` as shown below, otherwise `email` will
    2.  // **not** be lowercased.
    3.  M.updateOne({}, { $set: { email: 'SomeEmail@example.COM' } }, { runSettersOnQuery: true });

    show code

    1. SchemaString.prototype.uppercase = function(shouldApply) {
    2.   if (arguments.length > 0 && !shouldApply) {
    3.     return this;
    4.   }
    5.   return this.set(function(v, self) {
    6.     if (typeof v !== 'string') {
    7.       v = self.cast(v);
    8.     }
    9.     if (v) {
    10.       return v.toUpperCase();
    11.     }
    12.     return v;
    13.   });
    14. };

    SchemaString.schemaName

    This schema type’s name, to defend against minifiers that mangle
    function names.

    show code

    1. SchemaString.schemaName = 'String';

  • schema/date.js

    SchemaDate#cast(value)

    Casts to date

    Parameters:

    show code

    1. SchemaDate.prototype.cast = function(value) {
    2.   // If null or undefined
    3.   if (value === null || value === void 0 || value === '') {
    4.     return null;
    5.   }
    7.   if (value instanceof Date) {
    8.     if (isNaN(value.valueOf())) {
    9.       throw new CastError('date', value, this.path);
    10.     }
    12.     return value;
    13.   }
    15.   var date;
    17.   if (typeof value === 'boolean') {
    18.     throw new CastError('date', value, this.path);
    19.   }
    21.   if (value instanceof Number || typeof value === 'number'
    22.       || String(value) == Number(value)) {
    23.     // support for timestamps
    24.     date = new Date(Number(value));
    25.   } else if (value.valueOf) {
    26.     // support for moment.js
    27.     date = new Date(value.valueOf());
    28.   }
    30.   if (!isNaN(date.valueOf())) {
    31.     return date;
    32.   }
    34.   throw new CastError('date', value, this.path);
    35. };

    SchemaDate#castForQuery($conditional, [value])

    Casts contents for queries.

    Parameters:

    • $conditional <String>
    • [value] <T>

    show code

    1. SchemaDate.prototype.castForQuery = function($conditional, val) {
    2.   var handler;
    4.   if (arguments.length !== 2) {
    5.     return this._castForQuery($conditional);
    6.   }
    8.   handler = this.$conditionalHandlers[$conditional];
    10.   if (!handler) {
    11.     throw new Error('Can\'t use ' + $conditional + ' with Date.');
    12.   }
    14.   return handler.call(this, val);
    15. };

    SchemaDate#checkRequired(value, doc)

    Check if the given value satisfies a required validator. To satisfy
    a required validator, the given value must be an instance of Date.

    Parameters:

    Returns:

    show code

    1. SchemaDate.prototype.checkRequired = function(value) {
    2.   return value instanceof Date;
    3. };

    SchemaDate#expires(when)

    Declares a TTL index (rounded to the nearest second) for Date types only.

    Parameters:

    Returns:

    This sets the expireAfterSeconds index option available in MongoDB >= 2.1.2.
    This index type is only compatible with Date types.

    Example:

    1. // expire in 24 hours
    2. new Schema({ createdAt: { type: Date, expires: 60*60*24 }});

    expires utilizes the ms module from guille allowing us to use a friendlier syntax:

    Example:

    1. // expire in 24 hours
    2. new Schema({ createdAt: { type: Date, expires: '24h' }});
    4. // expire in 1.5 hours
    5. new Schema({ createdAt: { type: Date, expires: '1.5h' }});
    7. // expire in 7 days
    8. var schema = new Schema({ createdAt: Date });
    9. schema.path('createdAt').expires('7d');

    show code

    1. SchemaDate.prototype.expires = function(when) {
    2.   if (!this._index || this._index.constructor.name !== 'Object') {
    3.     this._index = {};
    4.   }
    6.   this._index.expires = when;
    7.   utils.expires(this._index);
    8.   return this;
    9. };

    SchemaDate#max(maximum, [message])

    Sets a maximum date validator.

    Parameters:

    • maximum <Date> date
    • [message] <String> optional custom error message

    Returns:

    See:

    Example:

    1. var s = new Schema({ d: { type: Date, max: Date('2014-01-01') })
    2. var M = db.model('M', s)
    3. var m = new M({ d: Date('2014-12-08') })
    4. m.save(function (err) {
    5.   console.error(err) // validator error
    6.   m.d = Date('2013-12-31');
    7.   m.save() // success
    8. })
    10. // custom error messages
    11. // We can also use the special {MAX} token which will be replaced with the invalid value
    12. var max = [Date('2014-01-01'), 'The value of path `{PATH}` ({VALUE}) exceeds the limit ({MAX}).'];
    13. var schema = new Schema({ d: { type: Date, max: max })
    14. var M = mongoose.model('M', schema);
    15. var s= new M({ d: Date('2014-12-08') });
    16. s.validate(function (err) {
    17.   console.log(String(err)) // ValidationError: The value of path `d` (2014-12-08) exceeds the limit (2014-01-01).
    18. })

    show code

    1. SchemaDate.prototype.max = function(value, message) {
    2.   if (this.maxValidator) {
    3.     this.validators = this.validators.filter(function(v) {
    4.       return v.validator !== this.maxValidator;
    5.     }, this);
    6.   }
    8.   if (value) {
    9.     var msg = message || MongooseError.messages.Date.max;
    10.     msg = msg.replace(/{MAX}/, (value === Date.now ? 'Date.now()' : this.cast(value).toString()));
    11.     var _this = this;
    12.     this.validators.push({
    13.       validator: this.maxValidator = function(val) {
    14.         var max = (value === Date.now ? value() : _this.cast(value));
    15.         return val === null || val.valueOf() <= max.valueOf();
    16.       },
    17.       message: msg,
    18.       type: 'max',
    19.       max: value
    20.     });
    21.   }
    23.   return this;
    24. };

    SchemaDate#min(value, [message])

    Sets a minimum date validator.

    Parameters:

    • value <Date> minimum date
    • [message] <String> optional custom error message

    Returns:

    See:

    Example:

    1. var s = new Schema({ d: { type: Date, min: Date('1970-01-01') })
    2. var M = db.model('M', s)
    3. var m = new M({ d: Date('1969-12-31') })
    4. m.save(function (err) {
    5.   console.error(err) // validator error
    6.   m.d = Date('2014-12-08');
    7.   m.save() // success
    8. })
    10. // custom error messages
    11. // We can also use the special {MIN} token which will be replaced with the invalid value
    12. var min = [Date('1970-01-01'), 'The value of path `{PATH}` ({VALUE}) is beneath the limit ({MIN}).'];
    13. var schema = new Schema({ d: { type: Date, min: min })
    14. var M = mongoose.model('M', schema);
    15. var s= new M({ d: Date('1969-12-31') });
    16. s.validate(function (err) {
    17.   console.log(String(err)) // ValidationError: The value of path `d` (1969-12-31) is before the limit (1970-01-01).
    18. })

    show code

    1. SchemaDate.prototype.min = function(value, message) {
    2.   if (this.minValidator) {
    3.     this.validators = this.validators.filter(function(v) {
    4.       return v.validator !== this.minValidator;
    5.     }, this);
    6.   }
    8.   if (value) {
    9.     var msg = message || MongooseError.messages.Date.min;
    10.     msg = msg.replace(/{MIN}/, (value === Date.now ? 'Date.now()' : this.cast(value).toString()));
    11.     var _this = this;
    12.     this.validators.push({
    13.       validator: this.minValidator = function(val) {
    14.         var min = (value === Date.now ? value() : _this.cast(value));
    15.         return val === null || val.valueOf() >= min.valueOf();
    16.       },
    17.       message: msg,
    18.       type: 'min',
    19.       min: value
    20.     });
    21.   }
    23.   return this;
    24. };

    SchemaDate(key, options)

    Date SchemaType constructor.

    Parameters:

    Inherits:

    show code

    1. function SchemaDate(key, options) {
    2.   SchemaType.call(this, key, options, 'Date');
    3. }

    SchemaDate.schemaName

    This schema type’s name, to defend against minifiers that mangle
    function names.

    show code

    1. SchemaDate.schemaName = 'Date';

  • schema/embedded.js

    Embedded#cast(value)

    Casts contents

    Parameters:

    show code

    1. Embedded.prototype.cast = function(val, doc, init, priorVal) {
    2.   if (val && val.$isSingleNested) {
    3.     return val;
    4.   }
    6.   var Constructor = this.caster;
    7.   var discriminatorKey = Constructor.schema.options.discriminatorKey;
    8.   if (val != null &&
    9.       Constructor.discriminators &&
    10.       typeof val[discriminatorKey] === 'string' &&
    11.       Constructor.discriminators[val[discriminatorKey]]) {
    12.     Constructor = Constructor.discriminators[val[discriminatorKey]];
    13.   }
    15.   var subdoc;
    16.   if (init) {
    17.     subdoc = new Constructor(void 0, doc ? doc.$__.selected : void 0, doc);
    18.     subdoc.init(val);
    19.   } else {
    20.     if (Object.keys(val).length === 0) {
    21.       return new Constructor({}, doc ? doc.$__.selected : void 0, doc);
    22.     }
    24.     return new Constructor(val, doc ? doc.$__.selected : void 0, doc, undefined, {
    25.       priorDoc: priorVal
    26.     });
    27.   }
    29.   return subdoc;
    30. };

    Embedded#castForQuery([$conditional], value)

    Casts contents for query

    Parameters:

    • [$conditional] <string> optional query operator (like $eq or $in)
    • value <T>

    show code

    1. Embedded.prototype.castForQuery = function($conditional, val) {
    2.   var handler;
    3.   if (arguments.length === 2) {
    4.     handler = this.$conditionalHandlers[$conditional];
    5.     if (!handler) {
    6.       throw new Error('Can\'t use ' + $conditional);
    7.     }
    8.     return handler.call(this, val);
    9.   }
    10.   val = $conditional;
    11.   if (val == null) {
    12.     return val;
    13.   }
    15.   if (this.options.runSetters) {
    16.     val = this._applySetters(val);
    17.   }
    19.   return new this.caster(val);
    20. };

    Embedded#discriminator(name, schema)

    Adds a discriminator to this property

    Parameters:

    • name <String>
    • schema <Schema> fields to add to the schema for instances of this sub-class

    show code

    1. Embedded.prototype.discriminator = function(name, schema) {
    2.   discriminator(this.caster, name, schema);
    4.   this.caster.discriminators[name] = _createConstructor(schema);
    6.   return this.caster.discriminators[name];
    7. };

    Embedded#doValidate()

    Async validation on this single nested doc.

    show code

    1. Embedded.prototype.doValidate = function(value, fn, scope) {
    2.   var Constructor = this.caster;
    3.   var discriminatorKey = Constructor.schema.options.discriminatorKey;
    4.   if (value != null &&
    5.       Constructor.discriminators &&
    6.       typeof value[discriminatorKey] === 'string' &&
    7.       Constructor.discriminators[value[discriminatorKey]]) {
    8.     Constructor = Constructor.discriminators[value[discriminatorKey]];
    9.   }
    11.   SchemaType.prototype.doValidate.call(this, value, function(error) {
    12.     if (error) {
    13.       return fn(error);
    14.     }
    15.     if (!value) {
    16.       return fn(null);
    17.     }
    19.     if (!(value instanceof Constructor)) {
    20.       value = new Constructor(value);
    21.     }
    22.     value.validate({__noPromise: true}, fn);
    23.   }, scope);
    24. };

    Embedded#doValidateSync()

    Synchronously validate this single nested doc

    show code

    1. Embedded.prototype.doValidateSync = function(value, scope) {
    2.   var schemaTypeError = SchemaType.prototype.doValidateSync.call(this, value, scope);
    3.   if (schemaTypeError) {
    4.     return schemaTypeError;
    5.   }
    6.   if (!value) {
    7.     return;
    8.   }
    9.   return value.validateSync();
    10. };

    Embedded(schema, key, options)

    Sub-schema schematype constructor

    Parameters:

    Inherits:

    show code

    1. function Embedded(schema, path, options) {
    2.   this.caster = _createConstructor(schema);
    3.   this.caster.prototype.$basePath = path;
    4.   this.schema = schema;
    5.   this.$isSingleNested = true;
    6.   SchemaType.call(this, path, options, 'Embedded');
    7. }

  • schema/buffer.js

    SchemaBuffer#cast(value, doc, init)

    Casts contents

    Parameters:

    show code

    1. SchemaBuffer.prototype.cast = function(value, doc, init) {
    2.   var ret;
    3.   if (SchemaType._isRef(this, value, doc, init)) {
    4.     // wait! we may need to cast this to a document
    6.     if (value === null || value === undefined) {
    7.       return value;
    8.     }
    10.     // lazy load
    11.     Document || (Document = require('./../document'));
    13.     if (value instanceof Document) {
    14.       value.$__.wasPopulated = true;
    15.       return value;
    16.     }
    18.     // setting a populated path
    19.     if (Buffer.isBuffer(value)) {
    20.       return value;
    21.     } else if (!utils.isObject(value)) {
    22.       throw new CastError('buffer', value, this.path);
    23.     }
    25.     // Handle the case where user directly sets a populated
    26.     // path to a plain object; cast to the Model used in
    27.     // the population query.
    28.     var path = doc.$__fullPath(this.path);
    29.     var owner = doc.ownerDocument ? doc.ownerDocument() : doc;
    30.     var pop = owner.populated(path, true);
    31.     ret = new pop.options.model(value);
    32.     ret.$__.wasPopulated = true;
    33.     return ret;
    34.   }
    36.   // documents
    37.   if (value && value._id) {
    38.     value = value._id;
    39.   }
    41.   if (value && value.isMongooseBuffer) {
    42.     return value;
    43.   }
    45.   if (Buffer.isBuffer(value)) {
    46.     if (!value || !value.isMongooseBuffer) {
    47.       value = new MongooseBuffer(value, [this.path, doc]);
    48.       if (this.options.subtype != null) {
    49.         value._subtype = this.options.subtype;
    50.       }
    51.     }
    53.     return value;
    54.   } else if (value instanceof Binary) {
    55.     ret = new MongooseBuffer(value.value(true), [this.path, doc]);
    56.     if (typeof value.sub_type !== 'number') {
    57.       throw new CastError('buffer', value, this.path);
    58.     }
    59.     ret._subtype = value.sub_type;
    60.     return ret;
    61.   }
    63.   if (value === null) {
    64.     return value;
    65.   }
    67.   var type = typeof value;
    68.   if (type === 'string' || type === 'number' || Array.isArray(value)) {
    69.     if (type === 'number') {
    70.       value = [value];
    71.     }
    72.     ret = new MongooseBuffer(value, [this.path, doc]);
    73.     if (this.options.subtype != null) {
    74.       ret._subtype = this.options.subtype;
    75.     }
    76.     return ret;
    77.   }
    79.   throw new CastError('buffer', value, this.path);
    80. };

    SchemaBuffer#castForQuery($conditional, [value])

    Casts contents for queries.

    Parameters:

    • $conditional <String>
    • [value] <T>

    show code

    1. SchemaBuffer.prototype.castForQuery = function($conditional, val) {
    2.   var handler;
    3.   if (arguments.length === 2) {
    4.     handler = this.$conditionalHandlers[$conditional];
    5.     if (!handler) {
    6.       throw new Error('Can\'t use ' + $conditional + ' with Buffer.');
    7.     }
    8.     return handler.call(this, val);
    9.   }
    10.   val = $conditional;
    11.   var casted = this._castForQuery(val);
    12.   return casted ? casted.toObject({ transform: false, virtuals: false }) : casted;
    13. };

    SchemaBuffer#checkRequired(value, doc)

    Check if the given value satisfies a required validator. To satisfy a
    required validator, a buffer must not be null or undefined and have
    non-zero length.

    Parameters:

    Returns:

    show code

    1. SchemaBuffer.prototype.checkRequired = function(value, doc) {
    2.   if (SchemaType._isRef(this, value, doc, true)) {
    3.     return !!value;
    4.   }
    5.   return !!(value && value.length);
    6. };

    SchemaBuffer(key, options)

    Buffer SchemaType constructor

    Parameters:

    Inherits:

    show code

    1. function SchemaBuffer(key, options) {
    2.   SchemaType.call(this, key, options, 'Buffer');
    3. }

    SchemaBuffer#subtype(subtype)

    Sets the default subtype
    for this buffer. You can find a list of allowed subtypes here.

    Parameters:

    • subtype <Number> the default subtype

    Returns:

    Example:

    1. var s = new Schema({ uuid: { type: Buffer, subtype: 4 });
    2. var M = db.model('M', s);
    3. var m = new M({ uuid: 'test string' });
    4. m.uuid._subtype; // 4

    show code

    1. SchemaBuffer.prototype.subtype = function(subtype) {
    2.   this.options.subtype = subtype;
    3.   return this;
    4. };

    SchemaBuffer.schemaName

    This schema type’s name, to defend against minifiers that mangle
    function names.

    show code

    1. SchemaBuffer.schemaName = 'Buffer';

  • schema/mixed.js

    Mixed#cast(value)

    Casts val for Mixed.

    Parameters:

    this is a no-op

    show code

    1. Mixed.prototype.cast = function(val) {
    2.   return val;
    3. };

    Mixed#castForQuery($cond, [val])

    Casts contents for queries.

    Parameters:

    show code

    1. Mixed.prototype.castForQuery = function($cond, val) {
    2.   if (arguments.length === 2) {
    3.     return val;
    4.   }
    5.   return $cond;
    6. };

    Mixed(path, options)

    Mixed SchemaType constructor.

    Parameters:

    Inherits:

    show code

    1. function Mixed(path, options) {
    2.   if (options && options.default) {
    3.     var def = options.default;
    4.     if (Array.isArray(def) && def.length === 0) {
    5.       // make sure empty array defaults are handled
    6.       options.default = Array;
    7.     } else if (!options.shared && utils.isObject(def) && Object.keys(def).length === 0) {
    8.       // prevent odd "shared" objects between documents
    9.       options.default = function() {
    10.         return {};
    11.       };
    12.     }
    13.   }
    15.   SchemaType.call(this, path, options, 'Mixed');
    16. }

    Mixed.schemaName

    This schema type’s name, to defend against minifiers that mangle
    function names.

    show code

    1. Mixed.schemaName = 'Mixed';

  • services/cursor/eachAsync.js

    module.exports(next, fn, options, [callback])

    Execute fn for every document in the cursor. If fn returns a promise,
    will wait for the promise to resolve before iterating on to the next one.
    Returns a promise that resolves when done.

    Parameters:

    • next <Function> the thunk to call to get the next document
    • fn <Function>
    • options <Object>
    • [callback] <Function> executed when all docs have been processed

    Returns:

  • services/updateValidators.js

    module.exports(query, schema, castedDoc, options)

    Applies validators and defaults to update and findOneAndUpdate operations,
    specifically passing a null doc as this to validators and defaults

    Parameters:

  • services/setDefaultsOnInsert.js

    module.exports(filter, schema, castedDoc, options)

    Applies defaults to update and findOneAndUpdate operations.

    Parameters:

  • connection.js

    Connection#_close(force, callback)

    Handles closing the connection

    Parameters:

    show code

    1. Connection.prototype._close = function(force, callback) {
    2.   var _this = this;
    3.   this._closeCalled = true;
    5.   switch (this.readyState) {
    6.     case 0: // disconnected
    7.       callback && callback();
    8.       break;
    10.     case 1: // connected
    11.     case 4: // unauthorized
    12.       this.readyState = STATES.disconnecting;
    13.       this.doClose(force, function(err) {
    14.         if (err) {
    15.           _this.error(err, callback);
    16.         } else {
    17.           _this.onClose(force);
    18.           callback && callback();
    19.         }
    20.       });
    21.       break;
    23.     case 2: // connecting
    24.       this.once('open', function() {
    25.         _this.close(callback);
    26.       });
    27.       break;
    29.     case 3: // disconnecting
    30.       if (!callback) {
    31.         break;
    32.       }
    33.       this.once('close', function() {
    34.         callback();
    35.       });
    36.       break;
    37.   }
    39.   return this;
    40. };

    Connection#_open(callback)

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

    Parameters:

    show code

    1. Connection.prototype._open = function(emit, callback) {
    2.   this.readyState = STATES.connecting;
    3.   this._closeCalled = false;
    5.   var _this = this;
    7.   var method = this.replica
    8.       ? 'doOpenSet'
    9.       : 'doOpen';
    11.   // open connection
    12.   this[method](function(err) {
    13.     if (err) {
    14.       _this.readyState = STATES.disconnected;
    15.       if (_this._hasOpened) {
    16.         if (callback) {
    17.           callback(err);
    18.         }
    19.       } else {
    20.         _this.error(err, emit && callback);
    21.       }
    22.       return;
    23.     }
    25.     _this.onOpen(callback);
    26.   });
    27. };

    Connection#authMechanismDoesNotRequirePassword()

    @brief Returns a boolean value that specifies if the current authentication mechanism needs a
    password to authenticate according to the auth objects passed into the open/openSet methods.

    Returns:

    • <Boolean> true if the authentication mechanism specified in the options object requires

    show code

    1. Connection.prototype.authMechanismDoesNotRequirePassword = function() {
    2.   if (this.options && this.options.auth) {
    3.     return authMechanismsWhichDontRequirePassword.indexOf(this.options.auth.authMechanism) >= 0;
    4.   }
    5.   return true;
    6. };

    Connection#close([force], [callback])

    Closes the connection

    Parameters:

    Returns:

    show code

    1. Connection.prototype.close = function(force, callback) {
    2.   var _this = this;
    3.   var Promise = PromiseProvider.get();
    5.   if (typeof force === 'function') {
    6.     callback = force;
    7.     force = false;
    8.   }
    10.   this.$wasForceClosed = !!force;
    12.   return new Promise.ES6(function(resolve, reject) {
    13.     _this._close(force, function(error) {
    14.       callback && callback(error);
    15.       if (error) {
    16.         reject(error);
    17.         return;
    18.       }
    19.       resolve();
    20.     });
    21.   });
    22. };

    Connection#collection(name, [options])

    Retrieves a collection, creating it if not cached.

    Parameters:

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

    Returns:

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

    show code

    1. Connection.prototype.collection = function(name, options) {
    2.   options = options ? utils.clone(options, { retainKeyOrder: true }) : {};
    3.   options.$wasForceClosed = this.$wasForceClosed;
    4.   if (!(name in this.collections)) {
    5.     this.collections[name] = new Collection(name, this, options);
    6.   }
    7.   return this.collections[name];
    8. };

    Connection(base)

    Connection constructor

    Parameters:

    Inherits:

    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 primary and at least one seconaries specified in the connection string are connected.

    • all: 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

    1. function Connection(base) {
    2.   this.base = base;
    3.   this.collections = {};
    4.   this.models = {};
    5.   this.config = {autoIndex: true};
    6.   this.replica = false;
    7.   this.hosts = null;
    8.   this.host = null;
    9.   this.port = null;
    10.   this.user = null;
    11.   this.pass = null;
    12.   this.name = null;
    13.   this.options = null;
    14.   this.otherDbs = [];
    15.   this.states = STATES;
    16.   this._readyState = STATES.disconnected;
    17.   this._closeCalled = false;
    18.   this._hasOpened = false;
    19. }

    (collection, [options], [callback])

    Helper for createCollection(). Will explicitly create the given collection
    with specified options. Used to create capped collections
    and views from mongoose.

    Parameters:

    Returns:

    Options are passed down without modification to the MongoDB driver’s createCollection() function

    show code

    1. Connection.prototype.createCollection = _wrapConnHelper(function createCollection(collection, options, cb) {
    2.   if (typeof options === 'function') {
    3.     cb = options;
    4.     options = {};
    5.   }
    6.   this.db.createCollection(collection, options, cb);
    7. });

    (collection, [callback])

    Helper for dropCollection(). Will delete the given collection, including
    all documents and indexes.

    Parameters:

    Returns:

    show code

    1. Connection.prototype.dropCollection = _wrapConnHelper(function dropCollection(collection, cb) {
    2.   this.db.dropCollection(collection, cb);
    3. });

    ([callback])

    Helper for dropDatabase(). Deletes the given database, including all
    collections, documents, and indexes.

    Parameters:

    Returns:

    show code

    1. Connection.prototype.dropDatabase = _wrapConnHelper(function dropDatabase(cb) {
    2.   this.db.dropDatabase(cb);
    3. });

    Connection#error(err, callback)

    error

    Parameters:

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

    show code

    1. Connection.prototype.error = function(err, callback) {
    2.   if (callback) {
    3.     return callback(err);
    4.   }
    5.   this.emit('error', err);
    6. };

    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:

    1. var mongoose = require('mongoose');
    2. var db = mongoose.createConnection(..);
    3. db.model('Venue', new Schema(..));
    4. var Ticket = db.model('Ticket', new Schema(..));
    5. 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:

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

    show code

    1. Connection.prototype.model = function(name, schema, collection) {
    2.   // collection name discovery
    3.   if (typeof schema === 'string') {
    4.     collection = schema;
    5.     schema = false;
    6.   }
    8.   if (utils.isObject(schema) && !schema.instanceOfSchema) {
    9.     schema = new Schema(schema);
    10.   }
    11.   if (schema && !schema.instanceOfSchema) {
    12.     throw new Error('The 2nd parameter to `mongoose.model()` should be a ' +
    13.       'schema or a POJO');
    14.   }
    16.   if (this.models[name] && !collection) {
    17.     // model exists but we are not subclassing with custom collection
    18.     if (schema && schema.instanceOfSchema && schema !== this.models[name].schema) {
    19.       throw new MongooseError.OverwriteModelError(name);
    20.     }
    21.     return this.models[name];
    22.   }
    24.   var opts = {cache: false, connection: this};
    25.   var model;
    27.   if (schema && schema.instanceOfSchema) {
    28.     // compile a model
    29.     model = this.base.model(name, schema, collection, opts);
    31.     // only the first model with this name is cached to allow
    32.     // for one-offs with custom collection names etc.
    33.     if (!this.models[name]) {
    34.       this.models[name] = model;
    35.     }
    37.     model.init();
    38.     return model;
    39.   }
    41.   if (this.models[name] && collection) {
    42.     // subclassing current model with alternate collection
    43.     model = this.models[name];
    44.     schema = model.prototype.schema;
    45.     var sub = model.__subclass(this, schema, collection);
    46.     // do not cache the sub model
    47.     return sub;
    48.   }
    50.   // lookup model in mongoose module
    51.   model = this.base.models[name];
    53.   if (!model) {
    54.     throw new MongooseError.MissingSchemaError(name);
    55.   }
    57.   if (this === model.prototype.db
    58.       && (!collection || collection === model.collection.name)) {
    59.     // model already uses this connection.
    61.     // only the first model with this name is cached to allow
    62.     // for one-offs with custom collection names etc.
    63.     if (!this.models[name]) {
    64.       this.models[name] = model;
    65.     }
    67.     return model;
    68.   }
    69.   this.models[name] = model.__subclass(this, schema, collection);
    70.   return this.models[name];
    71. };

    Connection#modelNames()

    Returns an array of model names created on this connection.

    Returns:

    show code

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

    Connection#onClose()

    Called when the connection closes

    show code

    1. Connection.prototype.onClose = function(force) {
    2.   this.readyState = STATES.disconnected;
    4.   // avoid having the collection subscribe to our event emitter
    5.   // to prevent 0.3 warning
    6.   for (var i in this.collections) {
    7.     if (utils.object.hasOwnProperty(this.collections, i)) {
    8.       this.collections[i].onClose(force);
    9.     }
    10.   }
    12.   this.emit('close', force);
    13. };

    Connection#onOpen()

    Called when the connection is opened

    show code

    1. Connection.prototype.onOpen = function(callback) {
    2.   var _this = this;
    4.   function open(err, isAuth) {
    5.     if (err) {
    6.       _this.readyState = isAuth ? STATES.unauthorized : STATES.disconnected;
    7.       _this.error(err, callback);
    8.       return;
    9.     }
    11.     _this.readyState = STATES.connected;
    13.     // avoid having the collection subscribe to our event emitter
    14.     // to prevent 0.3 warning
    15.     for (var i in _this.collections) {
    16.       if (utils.object.hasOwnProperty(_this.collections, i)) {
    17.         _this.collections[i].onOpen();
    18.       }
    19.     }
    21.     callback && callback();
    22.     _this.emit('open');
    23.   }
    25.   // re-authenticate if we're not already connected #3871
    26.   if (this._readyState !== STATES.connected && this.shouldAuthenticate()) {
    27.     _this.db.authenticate(_this.user, _this.pass, _this.options.auth, function(err) {
    28.       open(err, true);
    29.     });
    30.   } else {
    31.     open();
    32.   }
    33. };

    (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:

    options is a hash with the following possible properties:

    1. config  - passed to the connection config instance
    2. db      - passed to the connection db instance
    3. server  - passed to the connection server instance(s)
    4. replset - passed to the connection ReplSet instance
    5. user    - username for authentication
    6. pass    - password for authentication
    7. 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

    1. Connection.prototype.open = util.deprecate(function() {
    2.   var Promise = PromiseProvider.get();
    3.   var callback;
    5.   try {
    6.     callback = this._handleOpenArgs.apply(this, arguments);
    7.   } catch (error) {
    8.     return new Promise.ES6(function(resolve, reject) {
    9.       reject(error);
    10.     });
    11.   }
    13.   var _this = this;
    14.   var promise = new Promise.ES6(function(resolve, reject) {
    15.     _this._open(true, function(error) {
    16.       callback && callback(error);
    17.       if (error) {
    18.         // Error can be on same tick re: christkv/mongodb-core#157
    19.         setImmediate(function() {
    20.           reject(error);
    21.           if (!callback && !promise.$hasHandler) {
    22.             _this.emit('error', error);
    23.           }
    24.         });
    25.         return;
    26.       }
    27.       resolve();
    28.     });
    29.   });
    31.   // Monkey-patch `.then()` so if the promise is handled, we don't emit an
    32.   // `error` event.
    33.   var _then = promise.then;
    34.   promise.then = function(resolve, reject) {
    35.     promise.$hasHandler = true;
    36.     return _then.call(promise, resolve, reject);
    37.   };
    39.   return promise;
    40. }, '`open()` is deprecated in mongoose >= 4.11.0, use `openUri()` instead, or set the `useMongoClient` option if using `connect()` or `createConnection()`. See http://mongoosejs.com/docs/4.x/docs/connections.html#use-mongo-client');

    (uris, [database], [options], [callback])

    Opens the connection to a replica set.

    Parameters:

    • uris <String> MongoDB connection string
    • [database] <String> database name if not included in uris
    • [options] <Object> passed to the internal driver
    • [callback] <Function>

    See:

    Example:

    1. var db = mongoose.createConnection();
    2. db.openSet("mongodb://user:pwd@localhost:27020,localhost:27021,localhost:27012/mydb");

    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

    1. db      - passed to the connection db instance
    2. server  - passed to the connection server instance(s)
    3. replset - passed to the connection ReplSetServer instance
    4. user    - username for authentication
    5. pass    - password for authentication
    6. auth    - options for authentication (see http://mongodb.github.com/node-mongodb-native/api-generated/db.html#authenticate)
    7. 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.

    1. 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

    1. Connection.prototype.openSet = util.deprecate(function(uris, database, options, callback) {
    2.   var Promise = PromiseProvider.get();
    4.   try {
    5.     callback = this._handleOpenSetArgs.apply(this, arguments);
    6.   } catch (err) {
    7.     return new Promise.ES6(function(resolve, reject) {
    8.       reject(err);
    9.     });
    10.   }
    12.   var _this = this;
    13.   var emitted = false;
    14.   var promise = new Promise.ES6(function(resolve, reject) {
    15.     _this._open(true, function(error) {
    16.       callback && callback(error);
    17.       if (error) {
    18.         reject(error);
    19.         if (!callback && !promise.$hasHandler && !emitted) {
    20.           emitted = true;
    21.           _this.emit('error', error);
    22.         }
    23.         return;
    24.       }
    25.       resolve();
    26.     });
    27.   });
    29.   // Monkey-patch `.then()` so if the promise is handled, we don't emit an
    30.   // `error` event.
    31.   var _then = promise.then;
    32.   promise.then = function(resolve, reject) {
    33.     promise.$hasHandler = true;
    34.     return _then.call(promise, resolve, reject);
    35.   };
    37.   return promise;
    38. }, '`openSet()` is deprecated in mongoose >= 4.11.0, use `openUri()` instead, or set the `useMongoClient` option if using `connect()` or `createConnection()`. See http://mongoosejs.com/docs/4.x/docs/connections.html#use-mongo-client');

    Connection#openUri(uri, [options], [callback])

    Opens the connection with a URI using MongoClient.connect().

    Parameters:

    show code

    1. Connection.prototype.openUri = function(uri, options, callback) {
    2.   this.readyState = STATES.connecting;
    3.   this._closeCalled = false;
    5.   try {
    6.     var parsed = muri(uri);
    7.     this.name = parsed.db;
    8.     this.host = parsed.hosts[0].host || parsed.hosts[0].ipc;
    9.     this.port = parsed.hosts[0].port || 27017;
    10.     if (parsed.auth) {
    11.       this.user = parsed.auth.user;
    12.       this.pass = parsed.auth.pass;
    13.     }
    14.   } catch (error) {
    15.     this.error(error, callback);
    16.     throw error;
    17.   }
    19.   if (typeof options === 'function') {
    20.     callback = options;
    21.     options = null;
    22.   }
    24.   var Promise = PromiseProvider.get();
    25.   var _this = this;
    27.   if (options) {
    28.     options = utils.clone(options, { retainKeyOrder: true });
    29.     delete options.useMongoClient;
    30.     var autoIndex = options.config && options.config.autoIndex != null ?
    31.       options.config.autoIndex :
    32.       options.autoIndex;
    33.     if (autoIndex != null) {
    34.       this.config.autoIndex = autoIndex !== false;
    35.       delete options.config;
    36.       delete options.autoIndex;
    37.     }
    39.     // Backwards compat
    40.     if (options.user || options.pass) {
    41.       options.auth = options.auth || {};
    42.       options.auth.user = options.user;
    43.       options.auth.password = options.pass;
    44.       delete options.user;
    45.       delete options.pass;
    46.       this.user = options.auth.user;
    47.       this.pass = options.auth.password;
    48.     }
    50.     if (options.bufferCommands != null) {
    51.       options.bufferMaxEntries = 0;
    52.       this.config.bufferCommands = options.bufferCommands;
    53.       delete options.bufferCommands;
    54.     }
    55.   }
    57.   this._connectionOptions = options;
    59.   var promise = new Promise.ES6(function(resolve, reject) {
    60.     mongodb.MongoClient.connect(uri, options, function(error, db) {
    61.       if (error) {
    62.         _this.readyState = STATES.disconnected;
    63.         if (_this.listeners('error').length) {
    64.           _this.emit('error', error);
    65.         }
    66.         callback && callback(error);
    67.         return reject(error);
    68.       }
    69.       // Backwards compat for mongoose 4.x
    70.       db.on('reconnect', function() {
    71.         _this.readyState = STATES.connected;
    72.         _this.emit('reconnect');
    73.         _this.emit('reconnected');
    74.       });
    75.       db.s.topology.on('reconnectFailed', function() {
    76.         _this.emit('reconnectFailed');
    77.       });
    78.       db.s.topology.on('close', function() {
    79.         // Implicitly emits 'disconnected'
    80.         _this.readyState = STATES.disconnected;
    81.       });
    82.       db.on('timeout', function() {
    83.         _this.emit('timeout');
    84.       });
    86.       delete _this.then;
    87.       delete _this.catch;
    89.       _this.db = db;
    90.       _this.readyState = STATES.connected;
    92.       for (var i in _this.collections) {
    93.         if (utils.object.hasOwnProperty(_this.collections, i)) {
    94.           _this.collections[i].onOpen();
    95.         }
    96.       }
    98.       callback && callback(null, _this);
    99.       resolve(_this);
    100.       _this.emit('open');
    101.     });
    102.   });
    104.   this.then = function(resolve, reject) {
    105.     return promise.then(resolve, reject);
    106.   };
    107.   this.catch = function(reject) {
    108.     return promise.catch(reject);
    109.   };
    111.   return this;
    112. };

    Connection#optionsProvideAuthenticationData([options])

    @brief Returns a boolean value that specifies if the provided objects object provides enough
    data to authenticate with. Generally this is true if the username and password are both specified
    but in some authentication methods, a password is not required for authentication so only a username
    is required.

    Parameters:

    • [options] <Object> the options object passed into the open/openSet methods.

    Returns:

    • <Boolean> true if the provided options object provides enough data to authenticate with,

    show code

    1. Connection.prototype.optionsProvideAuthenticationData = function(options) {
    2.   return (options) &&
    3.       (options.user) &&
    4.       ((options.pass) || this.authMechanismDoesNotRequirePassword());
    5. };

    Connection#shouldAuthenticate()

    @brief Returns if the connection requires authentication after it is opened. Generally if a
    username and password are both provided than authentication is needed, but in some cases a
    password is not required.

    Returns:

    • <Boolean> true if the connection should be authenticated after it is opened, otherwise false.

    show code

    1. Connection.prototype.shouldAuthenticate = function() {
    2.   return (this.user !== null && this.user !== void 0) &&
    3.       ((this.pass !== null || this.pass !== void 0) || this.authMechanismDoesNotRequirePassword());
    4. };

    Connection#collections

    A hash of the collections associated with this connection

    show code

    1. Connection.prototype.collections;

    Connection#config

    A hash of the global options that are associated with this connection

    show code

    1. Connection.prototype.config;

    Connection#db

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

    show code

    1. Connection.prototype.db;

    Connection#readyState

    Connection ready state

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

    Each state change emits its associated event name.

    Example

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

    show code

    1. Object.defineProperty(Connection.prototype, 'readyState', {
    2.   get: function() {
    3.     return this._readyState;
    4.   },
    5.   set: function(val) {
    6.     if (!(val in STATES)) {
    7.       throw new Error('Invalid connection state: ' + val);
    8.     }
    10.     if (this._readyState !== val) {
    11.       this._readyState = val;
    12.       // loop over the otherDbs on this connection and change their state
    13.       for (var i = 0; i < this.otherDbs.length; i++) {
    14.         this.otherDbs[i].readyState = val;
    15.       }
    17.       if (STATES.connected === val) {
    18.         this._hasOpened = true;
    19.       }
    21.       this.emit(STATES[val]);
    22.     }
    23.   }
    24. });

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

    function Object() { [native code] }#$format()%20%7B%20%5Bnative%20code%5D%20%7D-%24format)

    Formatter for debug print args

    function Object() { [native code] }#$print()%20%7B%20%5Bnative%20code%5D%20%7D-%24print)

    Debug print helper

    NativeCollection#getIndexes(callback)

    Retreives information about this collections indexes.

    Parameters:

    NativeCollection()

    A node-mongodb-native collection implementation.

    Inherits:

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

    show code

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

    NativeCollection#onClose()

    Called when the connection closes

    show code

    1. NativeCollection.prototype.onClose = function(force) {
    2.   MongooseCollection.prototype.onClose.call(this, force);
    3. };

    NativeCollection#onOpen()

    Called when the connection opens.

    show code

    1. NativeCollection.prototype.onOpen = function() {
    2.   var _this = this;
    4.   // always get a new collection in case the user changed host:port
    5.   // of parent db instance when re-opening the connection.
    7.   if (!_this.opts.capped.size) {
    8.     // non-capped
    9.     callback(null, _this.conn.db.collection(_this.name));
    10.     return _this.collection;
    11.   }
    13.   // capped
    14.   return _this.conn.db.collection(_this.name, function(err, c) {
    15.     if (err) return callback(err);
    17.     // discover if this collection exists and if it is capped
    18.     _this.conn.db.listCollections({name: _this.name}).toArray(function(err, docs) {
    19.       if (err) {
    20.         return callback(err);
    21.       }
    22.       var doc = docs[0];
    23.       var exists = !!doc;
    25.       if (exists) {
    26.         if (doc.options && doc.options.capped) {
    27.           callback(null, c);
    28.         } else {
    29.           var msg = 'A non-capped collection exists with the name: ' + _this.name + '
    31. '
    32.               + ' To use this collection as a capped collection, please '
    33.               + 'first convert it.
    34. '
    35.               + ' http://www.mongodb.org/display/DOCS/Capped+Collections#CappedCollections-Convertingacollectiontocapped';
    36.           err = new Error(msg);
    37.           callback(err);
    38.         }
    39.       } else {
    40.         // create
    41.         var opts = utils.clone(_this.opts.capped);
    42.         opts.capped = true;
    43.         _this.conn.db.createCollection(_this.name, opts, callback);
    44.       }
    45.     });
    46.   });
    48.   function callback(err, collection) {
    49.     if (err) {
    50.       // likely a strict mode error
    51.       _this.conn.emit('error', err);
    52.     } else {
    53.       _this.collection = collection;
    54.       MongooseCollection.prototype.onOpen.call(_this);
    55.     }
    56.   }
    57. };

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

    NativeConnection#doClose([force], [fn])

    Closes the connection

    Parameters:

    Returns:

    show code

    1. NativeConnection.prototype.doClose = function(force, fn) {
    2.   this.db.close(force, fn);
    3.   return this;
    4. };

    NativeConnection#doOpen(fn)

    Opens the connection to MongoDB.

    Parameters:

    Returns:

    show code

    1. NativeConnection.prototype.doOpen = function(fn) {
    2.   var _this = this;
    3.   var server = new Server(this.host, this.port, this.options.server);
    5.   if (this.options && this.options.mongos) {
    6.     var mongos = new Mongos([server], this.options.mongos);
    7.     this.db = new Db(this.name, mongos, this.options.db);
    8.   } else {
    9.     this.db = new Db(this.name, server, this.options.db);
    10.   }
    12.   this.db.open(function(err) {
    13.     listen(_this);
    15.     if (!mongos) {
    16.       server.s.server.on('error', function(error) {
    17.         if (/after \d+ attempts/.test(error.message)) {
    18.           _this.emit('error', new DisconnectedError(server.s.server.name));
    19.         }
    20.       });
    21.     }
    23.     if (err) return fn(err);
    25.     fn();
    26.   });
    28.   return this;
    29. };

    NativeConnection#doOpenSet(fn)

    Opens a connection to a MongoDB ReplicaSet.

    Parameters:

    Returns:

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

    show code

    1. NativeConnection.prototype.doOpenSet = function(fn) {
    2.   var servers = [],
    3.       _this = this;
    5.   this.hosts.forEach(function(server) {
    6.     var host = server.host || server.ipc;
    7.     var port = server.port || 27017;
    8.     servers.push(new Server(host, port, _this.options.server));
    9.   });
    11.   var server = this.options.mongos
    12.     ? new Mongos(servers, this.options.mongos)
    13.     : new ReplSetServers(servers, this.options.replset || this.options.replSet);
    14.   this.db = new Db(this.name, server, this.options.db);
    16.   this.db.s.topology.on('left', function(data) {
    17.     _this.emit('left', data);
    18.   });
    20.   this.db.s.topology.on('joined', function(data) {
    21.     _this.emit('joined', data);
    22.   });
    24.   this.db.on('fullsetup', function() {
    25.     _this.emit('fullsetup');
    26.   });
    28.   this.db.on('all', function() {
    29.     _this.emit('all');
    30.   });
    32.   this.db.open(function(err) {
    33.     if (err) return fn(err);
    34.     fn();
    35.     listen(_this);
    36.   });
    38.   return this;
    39. };

    NativeConnection()

    A node-mongodb-native connection implementation.

    Inherits:

    show code

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

    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

    1. NativeConnection.prototype.parseOptions = function(passed, connStrOpts) {
    2.   var o = passed ? require('../../utils').clone(passed) : {};
    4.   o.db || (o.db = {});
    5.   o.auth || (o.auth = {});
    6.   o.server || (o.server = {});
    7.   o.replset || (o.replset = o.replSet) || (o.replset = {});
    8.   o.server.socketOptions || (o.server.socketOptions = {});
    9.   o.replset.socketOptions || (o.replset.socketOptions = {});
    10.   o.mongos || (o.mongos = (connStrOpts && connStrOpts.mongos));
    11.   (o.mongos === true) && (o.mongos = {});
    13.   var opts = connStrOpts || {};
    14.   Object.keys(opts).forEach(function(name) {
    15.     switch (name) {
    16.       case 'ssl':
    17.         o.server.ssl = opts.ssl;
    18.         o.replset.ssl = opts.ssl;
    19.         o.mongos && (o.mongos.ssl = opts.ssl);
    20.         break;
    21.       case 'poolSize':
    22.         if (typeof o.server[name] === 'undefined') {
    23.           o.server[name] = o.replset[name] = opts[name];
    24.         }
    25.         break;
    26.       case 'slaveOk':
    27.         if (typeof o.server.slave_ok === 'undefined') {
    28.           o.server.slave_ok = opts[name];
    29.         }
    30.         break;
    31.       case 'autoReconnect':
    32.         if (typeof o.server.auto_reconnect === 'undefined') {
    33.           o.server.auto_reconnect = opts[name];
    34.         }
    35.         break;
    36.       case 'socketTimeoutMS':
    37.       case 'connectTimeoutMS':
    38.         if (typeof o.server.socketOptions[name] === 'undefined') {
    39.           o.server.socketOptions[name] = o.replset.socketOptions[name] = opts[name];
    40.         }
    41.         break;
    42.       case 'authdb':
    43.         if (typeof o.auth.authdb === 'undefined') {
    44.           o.auth.authdb = opts[name];
    45.         }
    46.         break;
    47.       case 'authSource':
    48.         if (typeof o.auth.authSource === 'undefined') {
    49.           o.auth.authSource = opts[name];
    50.         }
    51.         break;
    52.       case 'authMechanism':
    53.         if (typeof o.auth.authMechanism === 'undefined') {
    54.           o.auth.authMechanism = opts[name];
    55.         }
    56.         break;
    57.       case 'retries':
    58.       case 'reconnectWait':
    59.       case 'rs_name':
    60.         if (typeof o.replset[name] === 'undefined') {
    61.           o.replset[name] = opts[name];
    62.         }
    63.         break;
    64.       case 'replicaSet':
    65.         if (typeof o.replset.rs_name === 'undefined') {
    66.           o.replset.rs_name = opts[name];
    67.         }
    68.         break;
    69.       case 'readSecondary':
    70.         if (typeof o.replset.read_secondary === 'undefined') {
    71.           o.replset.read_secondary = opts[name];
    72.         }
    73.         break;
    74.       case 'nativeParser':
    75.         if (typeof o.db.native_parser === 'undefined') {
    76.           o.db.native_parser = opts[name];
    77.         }
    78.         break;
    79.       case 'w':
    80.       case 'safe':
    81.       case 'fsync':
    82.       case 'journal':
    83.       case 'wtimeoutMS':
    84.         if (typeof o.db[name] === 'undefined') {
    85.           o.db[name] = opts[name];
    86.         }
    87.         break;
    88.       case 'readPreference':
    89.         if (typeof o.db.readPreference === 'undefined') {
    90.           o.db.readPreference = opts[name];
    91.         }
    92.         break;
    93.       case 'readPreferenceTags':
    94.         if (typeof o.db.read_preference_tags === 'undefined') {
    95.           o.db.read_preference_tags = opts[name];
    96.         }
    97.         break;
    98.       case 'sslValidate':
    99.         o.server.sslValidate = opts.sslValidate;
    100.         o.replset.sslValidate = opts.sslValidate;
    101.         o.mongos && (o.mongos.sslValidate = opts.sslValidate);
    102.     }
    103.   });
    105.   if (!('auto_reconnect' in o.server)) {
    106.     o.server.auto_reconnect = true;
    107.   }
    109.   // mongoose creates its own ObjectIds
    110.   o.db.forceServerObjectId = false;
    112.   // default safe using new nomenclature
    113.   if (!('journal' in o.db || 'j' in o.db ||
    114.         'fsync' in o.db || 'safe' in o.db || 'w' in o.db)) {
    115.     o.db.w = 1;
    116.   }
    118.   if (o.promiseLibrary) {
    119.     o.db.promiseLibrary = o.promiseLibrary;
    120.   }
    122.   validate(o);
    123.   return o;
    124. };

    NativeConnection#useDb(name)

    Switches to a different database using the same connection pool.

    Parameters:

    • name <String> The database name

    Returns:

    Returns a new connection object, with the new db.

    show code

    1. NativeConnection.prototype.useDb = function(name) {
    2.   // we have to manually copy all of the attributes...
    3.   var newConn = new this.constructor();
    4.   newConn.name = name;
    5.   newConn.base = this.base;
    6.   newConn.collections = {};
    7.   newConn.models = {};
    8.   newConn.replica = this.replica;
    9.   newConn.hosts = this.hosts;
    10.   newConn.host = this.host;
    11.   newConn.port = this.port;
    12.   newConn.user = this.user;
    13.   newConn.pass = this.pass;
    14.   newConn.options = this.options;
    15.   newConn._readyState = this._readyState;
    16.   newConn._closeCalled = this._closeCalled;
    17.   newConn._hasOpened = this._hasOpened;
    18.   newConn._listening = false;
    20.   // First, when we create another db object, we are not guaranteed to have a
    21.   // db object to work with. So, in the case where we have a db object and it
    22.   // is connected, we can just proceed with setting everything up. However, if
    23.   // we do not have a db or the state is not connected, then we need to wait on
    24.   // the 'open' event of the connection before doing the rest of the setup
    25.   // the 'connected' event is the first time we'll have access to the db object
    27.   var _this = this;
    29.   if (this.db && this._readyState === STATES.connected) {
    30.     wireup();
    31.   } else {
    32.     this.once('connected', wireup);
    33.   }
    35.   function wireup() {
    36.     newConn.db = _this.db.db(name);
    37.     newConn.onOpen();
    38.     // setup the events appropriately
    39.     listen(newConn);
    40.   }
    42.   newConn.name = name;
    44.   // push onto the otherDbs stack, this is used when state changes
    45.   this.otherDbs.push(newConn);
    46.   newConn.otherDbs.push(this);
    48.   return newConn;
    49. };

    NativeConnection.STATES

    Expose the possible connection states.

    show code

    1. NativeConnection.STATES = STATES;

  • error/messages.js

    MongooseError.messages()

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

    show code

    1. var msg = module.exports = exports = {};
    3. msg.DocumentNotFoundError = null;
    5. msg.general = {};
    6. msg.general.default = 'Validator failed for path `{PATH}` with value `{VALUE}`';
    7. msg.general.required = 'Path `{PATH}` is required.';
    9. msg.Number = {};
    10. msg.Number.min = 'Path `{PATH}` ({VALUE}) is less than minimum allowed value ({MIN}).';
    11. msg.Number.max = 'Path `{PATH}` ({VALUE}) is more than maximum allowed value ({MAX}).';
    13. msg.Date = {};
    14. msg.Date.min = 'Path `{PATH}` ({VALUE}) is before minimum allowed value ({MIN}).';
    15. msg.Date.max = 'Path `{PATH}` ({VALUE}) is after maximum allowed value ({MAX}).';
    17. msg.String = {};
    18. msg.String.enum = '`{VALUE}` is not a valid enum value for path `{PATH}`.';
    19. msg.String.match = 'Path `{PATH}` is invalid ({VALUE}).';
    20. msg.String.minlength = 'Path `{PATH}` (`{VALUE}`) is shorter than the minimum allowed length ({MINLENGTH}).';
    21. msg.String.maxlength = 'Path `{PATH}` (`{VALUE}`) is longer than the maximum allowed length ({MAXLENGTH}).';
    1. // customize within each schema or globally like so
    2. var mongoose = require('mongoose');
    3. 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.

  • error/cast.js

    CastError(type, value)

    Casting Error constructor.

    Parameters:

    Inherits:

    show code

    1. function CastError(type, value, path, reason) {
    2.   var stringValue = util.inspect(value);
    3.   stringValue = stringValue.replace(/^'/, '"').replace(/'$/, '"');
    4.   if (stringValue.charAt(0) !== '"') {
    5.     stringValue = '"' + stringValue + '"';
    6.   }
    7.   MongooseError.call(this, 'Cast to ' + type + ' failed for value ' +
    8.     stringValue + ' at path "' + path + '"');
    9.   this.name = 'CastError';
    10.   if (Error.captureStackTrace) {
    11.     Error.captureStackTrace(this);
    12.   } else {
    13.     this.stack = new Error().stack;
    14.   }
    15.   this.stringValue = stringValue;
    16.   this.kind = type;
    17.   this.value = value;
    18.   this.path = path;
    19.   this.reason = reason;
    20. }

  • error/objectExpected.js

    ObjectExpectedError(type, value)

    Strict mode error constructor

    Parameters:

    Inherits:

    show code

    1. function ObjectExpectedError(path, val) {
    2.   MongooseError.call(this, 'Tried to set nested object field `' + path +
    3.     '` to primitive value `' + val + '` and strict mode is set to throw.');
    4.   this.name = 'ObjectExpectedError';
    5.   if (Error.captureStackTrace) {
    6.     Error.captureStackTrace(this);
    7.   } else {
    8.     this.stack = new Error().stack;
    9.   }
    10.   this.path = path;
    11. }

  • error/disconnected.js

    DisconnectedError(type, value)

    Casting Error constructor.

    Parameters:

    Inherits:

    show code

    1. function DisconnectedError(connectionString) {
    2.   MongooseError.call(this, 'Ran out of retries trying to reconnect to "' +
    3.     connectionString + '". Try setting `server.reconnectTries` and ' +
    4.     '`server.reconnectInterval` to something higher.');
    5.   this.name = 'DisconnectedError';
    6.   if (Error.captureStackTrace) {
    7.     Error.captureStackTrace(this);
    8.   } else {
    9.     this.stack = new Error().stack;
    10.   }
    11. }

  • error/objectParameter.js

    ObjectParameterError(value, paramName, fnName)

    Constructor for errors that happen when a parameter that’s expected to be
    an object isn’t an object

    Parameters:

    Inherits:

    show code

    1. function ObjectParameterError(value, paramName, fnName) {
    2.   MongooseError.call(this, 'Parameter "' + paramName + '" to ' + fnName +
    3.     '() must be an object, got ' + value.toString());
    4.   this.name = 'ObjectParameterError';
    5.   if (Error.captureStackTrace) {
    6.     Error.captureStackTrace(this);
    7.   } else {
    8.     this.stack = new Error().stack;
    9.   }
    10. }

  • error/validation.js

    ValidationError#toString()

    Console.log helper

    show code

    1. ValidationError.prototype.toString = function() {
    2.   return this.name + ': ' + _generateMessage(this);
    3. };

    ValidationError(instance)

    Document Validation Error

    Parameters:

    Inherits:

    show code

    1. function ValidationError(instance) {
    2.   this.errors = {};
    3.   this._message = '';
    4.   if (instance && instance.constructor.name === 'model') {
    5.     this._message = instance.constructor.modelName + ' validation failed';
    6.     MongooseError.call(this, this._message);
    7.   } else {
    8.     this._message = 'Validation failed';
    9.     MongooseError.call(this, this._message);
    10.   }
    11.   this.name = 'ValidationError';
    12.   if (Error.captureStackTrace) {
    13.     Error.captureStackTrace(this);
    14.   } else {
    15.     this.stack = new Error().stack;
    16.   }
    17.   if (instance) {
    18.     instance.errors = this.errors;
    19.   }
    20. }

  • error/validator.js

    ValidatorError(properties)

    Schema validator error

    Parameters:

    Inherits:

    show code

    1. function ValidatorError(properties) {
    2.   var msg = properties.message;
    3.   if (!msg) {
    4.     msg = MongooseError.messages.general.default;
    5.   }
    7.   var message = this.formatMessage(msg, properties);
    8.   MongooseError.call(this, message);
    9.   this.name = 'ValidatorError';
    10.   if (Error.captureStackTrace) {
    11.     Error.captureStackTrace(this);
    12.   } else {
    13.     this.stack = new Error().stack;
    14.   }
    15.   this.properties = properties;
    16.   this.kind = properties.type;
    17.   this.path = properties.path;
    18.   this.value = properties.value;
    19.   this.reason = properties.reason;
    20. }

  • error/index.js

    MongooseError(msg)

    MongooseError constructor

    Parameters:

    Inherits:

    show code

    1. function MongooseError(msg) {
    2.   Error.call(this);
    3.   if (Error.captureStackTrace) {
    4.     Error.captureStackTrace(this);
    5.   } else {
    6.     this.stack = new Error().stack;
    7.   }
    8.   this.message = msg;
    9.   this.name = 'MongooseError';
    10. }

    MongooseError.DocumentNotFoundError

    This error will be called when save() fails because the underlying
    document was not found. The constructor takes one parameter, the
    conditions that mongoose passed to update() when trying to update
    the document.

    show code

    1. MongooseError.DocumentNotFoundError = require('./notFound');

    MongooseError.messages

    The default built-in validator error messages.

    show code

    1. MongooseError.messages = require('./messages');
    3. // backward compat
    4. MongooseError.Messages = MongooseError.messages;

    See:

  • error/version.js

    VersionError()

    Version Error constructor.

    Inherits:

    show code

    1. function VersionError(doc, currentVersion, modifiedPaths) {
    2.   var modifiedPathsStr = modifiedPaths.join(', ');
    3.   MongooseError.call(this, 'No matching document found for id "' + doc._id +
    4.     '" version ' + currentVersion + ' modifiedPaths "' + modifiedPathsStr + '"');
    5.   this.name = 'VersionError';
    6.   this.version = currentVersion;
    7.   this.modifiedPaths = modifiedPaths;
    8. }

  • error/strict.js

    StrictModeError(type, value)

    Strict mode error constructor

    Parameters:

    Inherits:

    show code

    1. function StrictModeError(path, msg) {
    2.   msg = msg || 'Field `' + path + '` is not in schema and strict ' +
    3.     'mode is set to throw.';
    4.   MongooseError.call(this, msg);
    5.   this.name = 'StrictModeError';
    6.   if (Error.captureStackTrace) {
    7.     Error.captureStackTrace(this);
    8.   } else {
    9.     this.stack = new Error().stack;
    10.   }
    11.   this.path = path;
    12. }

  • aggregate.js

    Aggregate#addCursorFlag(flag, value)

    Adds a cursor flag

    Parameters:

    See:

    Example:

    1. Model.aggregate(..).addCursorFlag('noCursorTimeout', true).exec();

    show code

    1. Aggregate.prototype.addCursorFlag = function(flag, value) {
    2.   if (!this.options) {
    3.     this.options = {};
    4.   }
    5.   this.options[flag] = value;
    6.   return this;
    7. };

    Aggregate#addFields(arg)

    Appends a new $addFields operator to this aggregate pipeline.
    Requires MongoDB v3.4+ to work

    Parameters:

    • arg <Object> field specification

    Returns:

    See:

    Examples:

    1. // adding new fields based on existing fields
    2. aggregate.addFields({
    3.     newField: '$b.nested'
    4.   , plusTen: { $add: ['$val', 10]}
    5.   , sub: {
    6.        name: '$a'
    7.     }
    8. })
    10. // etc
    11. aggregate.addFields({ salary_k: { $divide: [ "$salary", 1000 ] } });

    show code

    1. Aggregate.prototype.addFields = function(arg) {
    2.   var fields = {};
    3.   if (typeof arg === 'object' && !util.isArray(arg)) {
    4.     Object.keys(arg).forEach(function(field) {
    5.       fields[field] = arg[field];
    6.     });
    7.   } else {
    8.     throw new Error('Invalid addFields() argument. Must be an object');
    9.   }
    10.   return this.append({$addFields: fields});
    11. };

    Aggregate([ops])

    Aggregate constructor used for building aggregation pipelines.

    Parameters:

    • [ops] <Object, Array> aggregation operator(s) or operator array

    See:

    Example:

    1. new Aggregate();
    2. new Aggregate({ $project: { a: 1, b: 1 } });
    3. new Aggregate({ $project: { a: 1, b: 1 } }, { $skip: 5 });
    4. new Aggregate([{ $project: { a: 1, b: 1 } }, { $skip: 5 }]);

    Returned when calling Model.aggregate().

    Example:

    1. Model
    2. .aggregate({ $match: { age: { $gte: 21 }}})
    3. .unwind('tags')
    4. .exec(callback)

    Note:

    • The documents returned are plain javascript objects, not mongoose documents (since any shape of document can be returned).
    • Requires MongoDB >= 2.1
    • Mongoose does not cast pipeline stages. new Aggregate({ $match: { _id: '00000000000000000000000a' } }); will not work unless _id is a string in the database. Use new Aggregate({ $match: { _id: mongoose.Types.ObjectId('00000000000000000000000a') } }); instead.

    show code

    1. function Aggregate() {
    2.   this._pipeline = [];
    3.   this._model = undefined;
    4.   this.options = {};
    6.   if (arguments.length === 1 && util.isArray(arguments[0])) {
    7.     this.append.apply(this, arguments[0]);
    8.   } else {
    9.     this.append.apply(this, arguments);
    10.   }
    11. }

    Aggregate#allowDiskUse(value, [tags])

    Sets the allowDiskUse option for the aggregation query (ignored for < 2.6.0)

    Parameters:

    • value <Boolean> Should tell server it can use hard drive to store data during aggregation.
    • [tags] <Array> optional tags for this query

    See:

    Example:

    1. Model.aggregate(..).allowDiskUse(true).exec(callback)

    show code

    1. Aggregate.prototype.allowDiskUse = function(value) {
    2.   this.options.allowDiskUse = value;
    3.   return this;
    4. };

    Aggregate#append(ops)

    Appends new operators to this aggregate pipeline

    Parameters:

    • ops <Object> operator(s) to append

    Returns:

    Examples:

    1. aggregate.append({ $project: { field: 1 }}, { $limit: 2 });
    3. // or pass an array
    4. var pipeline = [{ $match: { daw: 'Logic Audio X' }} ];
    5. aggregate.append(pipeline);

    show code

    1. Aggregate.prototype.append = function() {
    2.   var args = (arguments.length === 1 && util.isArray(arguments[0]))
    3.       ? arguments[0]
    4.       : utils.args(arguments);
    6.   if (!args.every(isOperator)) {
    7.     throw new Error('Arguments must be aggregate pipeline operators');
    8.   }
    10.   this._pipeline = this._pipeline.concat(args);
    12.   return this;
    13. };

    Aggregate#collation(collation)

    Adds a collation

    Parameters:

    See:

    Example:

    1. Model.aggregate(..).collation({ locale: 'en_US', strength: 1 }).exec();

    show code

    1. Aggregate.prototype.collation = function(collation) {
    2.   if (!this.options) {
    3.     this.options = {};
    4.   }
    5.   this.options.collation = collation;
    6.   return this;
    7. };

    Aggregate#cursor(options, options.batchSize, [options.useMongooseAggCursor])

    Sets the cursor option option for the aggregation query (ignored for < 2.6.0).
    Note the different syntax below: .exec() returns a cursor object, and no callback
    is necessary.

    Parameters:

    • options <Object>
    • options.batchSize <Number> set the cursor batch size
    • [options.useMongooseAggCursor] <Boolean> use experimental mongoose-specific aggregation cursor (for eachAsync() and other query cursor semantics)

    See:

    Example:

    1. var cursor = Model.aggregate(..).cursor({ batchSize: 1000, useMongooseAggCursor: true }).exec();
    2. cursor.each(function(error, doc) {
    3.   // use doc
    4. });

    show code

    1. Aggregate.prototype.cursor = function(options) {
    2.   if (!this.options) {
    3.     this.options = {};
    4.   }
    5.   this.options.cursor = options || {};
    6.   return this;
    7. };

    Aggregate#exec([callback])

    Executes the aggregate pipeline on the currently bound Model.

    Parameters:

    Returns:

    See:

    Example:

    1. aggregate.exec(callback);
    3. // Because a promise is returned, the `callback` is optional.
    4. var promise = aggregate.exec();
    5. promise.then(..);

    show code

    1. Aggregate.prototype.exec = function(callback) {
    2.   if (!this._model) {
    3.     throw new Error('Aggregate not bound to any Model');
    4.   }
    5.   var _this = this;
    6.   var model = this._model;
    7.   var Promise = PromiseProvider.get();
    8.   var options = utils.clone(this.options || {});
    9.   var pipeline = this._pipeline;
    10.   var collection = this._model.collection;
    12.   if (options && options.cursor) {
    13.     if (options.cursor.async) {
    14.       delete options.cursor.async;
    15.       return new Promise.ES6(function(resolve) {
    16.         if (!collection.buffer) {
    17.           process.nextTick(function() {
    18.             var cursor = collection.aggregate(pipeline, options);
    19.             decorateCursor(cursor);
    20.             resolve(cursor);
    21.             callback && callback(null, cursor);
    22.           });
    23.           return;
    24.         }
    25.         collection.emitter.once('queue', function() {
    26.           var cursor = collection.aggregate(pipeline, options);
    27.           decorateCursor(cursor);
    28.           resolve(cursor);
    29.           callback && callback(null, cursor);
    30.         });
    31.       });
    32.     } else if (options.cursor.useMongooseAggCursor) {
    33.       delete options.cursor.useMongooseAggCursor;
    34.       return new AggregationCursor(this);
    35.     }
    36.     var cursor = collection.aggregate(pipeline, options);
    37.     decorateCursor(cursor);
    38.     return cursor;
    39.   }
    41.   return new Promise.ES6(function(resolve, reject) {
    42.     if (!pipeline.length) {
    43.       var err = new Error('Aggregate has empty pipeline');
    44.       if (callback) {
    45.         callback(err);
    46.       }
    47.       reject(err);
    48.       return;
    49.     }
    51.     prepareDiscriminatorPipeline(_this);
    53.     model.hooks.execPre('aggregate', _this, function(error) {
    54.       if (error) {
    55.         var _opts = { error: error };
    56.         return model.hooks.execPost('aggregate', _this, [null], _opts, function(error) {
    57.           if (callback) {
    58.             callback(error);
    59.           }
    60.           reject(error);
    61.         });
    62.       }
    64.       collection.aggregate(pipeline, options, function(error, result) {
    65.         var _opts = { error: error };
    66.         model.hooks.execPost('aggregate', _this, [result], _opts, function(error, result) {
    67.           if (error) {
    68.             if (callback) {
    69.               callback(error);
    70.             }
    71.             reject(error);
    72.             return;
    73.           }
    75.           if (callback) {
    76.             callback(null, result);
    77.           }
    78.           resolve(result);
    79.         });
    80.       });
    81.     });
    82.   });
    83. };

    Aggregate#explain(callback)

    Execute the aggregation with explain

    Parameters:

    Returns:

    Example:

    1. Model.aggregate(..).explain(callback)

    show code

    1. Aggregate.prototype.explain = function(callback) {
    2.   var _this = this;
    3.   var Promise = PromiseProvider.get();
    4.   return new Promise.ES6(function(resolve, reject) {
    5.     if (!_this._pipeline.length) {
    6.       var err = new Error('Aggregate has empty pipeline');
    7.       if (callback) {
    8.         callback(err);
    9.       }
    10.       reject(err);
    11.       return;
    12.     }
    14.     prepareDiscriminatorPipeline(_this);
    16.     _this._model
    17.         .collection
    18.         .aggregate(_this._pipeline, _this.options || {})
    19.         .explain(function(error, result) {
    20.           if (error) {
    21.             if (callback) {
    22.               callback(error);
    23.             }
    24.             reject(error);
    25.             return;
    26.           }
    28.           if (callback) {
    29.             callback(null, result);
    30.           }
    31.           resolve(result);
    32.         });
    33.   });
    34. };

    Aggregate#facet(facet)

    Combines multiple aggregation pipelines.

    Parameters:

    Returns:

    See:

    Example:

    1. Model.aggregate(...)
    2.  .facet({
    3.    books: [{ groupBy: '$author' }],
    4.    price: [{ $bucketAuto: { groupBy: '$price', buckets: 2 } }]
    5.  })
    6.  .exec();
    8. // Output: { books: [...], price: [{...}, {...}] }

    show code

    1. Aggregate.prototype.facet = function(options) {
    2.   return this.append({$facet: options});
    3. };

    Aggregate#graphLookup(options)

    Appends new custom $graphLookup operator(s) to this aggregate pipeline, performing a recursive search on a collection.

    Parameters:

    • options <Object> to $graphLookup as described in the above link

    Returns:

    See:

    Note that graphLookup can only consume at most 100MB of memory, and does not allow disk use even if { allowDiskUse: true } is specified.

    Examples:

    1. // Suppose we have a collection of courses, where a document might look like `{ _id: 0, name: 'Calculus', prerequisite: 'Trigonometry'}` and `{ _id: 0, name: 'Trigonometry', prerequisite: 'Algebra' }`
    2.  aggregate.graphLookup({ from: 'courses', startWith: '$prerequisite', connectFromField: 'prerequisite', connectToField: 'name', as: 'prerequisites', maxDepth: 3 }) // this will recursively search the 'courses' collection up to 3 prerequisites

    show code

    1. Aggregate.prototype.graphLookup = function(options) {
    2.   var cloneOptions = {};
    3.   if (options) {
    4.     if (!utils.isObject(options)) {
    5.       throw new TypeError('Invalid graphLookup() argument. Must be an object.');
    6.     }
    8.     utils.mergeClone(cloneOptions, options);
    9.     var startWith = cloneOptions.startWith;
    11.     if (startWith && typeof startWith === 'string') {
    12.       cloneOptions.startWith = cloneOptions.startWith.charAt(0) === '$' ?
    13.         cloneOptions.startWith :
    14.         '$' + cloneOptions.startWith;
    15.     }
    17.   }
    18.   return this.append({ $graphLookup: cloneOptions });
    19. };

    Aggregate#group(arg)

    Appends a new custom $group operator to this aggregate pipeline.

    Parameters:

    • arg <Object> $group operator contents

    Returns:

    See:

    Examples:

    1. aggregate.group({ _id: "$department" });

    isOperator(obj)

    Checks whether an object is likely a pipeline operator

    Parameters:

    Returns:

    show code

    1. function isOperator(obj) {
    2.   var k;
    4.   if (typeof obj !== 'object') {
    5.     return false;
    6.   }
    8.   k = Object.keys(obj);
    10.   return k.length === 1 && k
    11.           .some(function(key) {
    12.             return key[0] === '$';
    13.           });
    14. }

    Aggregate#limit(num)

    Appends a new $limit operator to this aggregate pipeline.

    Parameters:

    • num <Number> maximum number of records to pass to the next stage

    Returns:

    See:

    Examples:

    1. aggregate.limit(10);

    Aggregate#lookup(options)

    Appends new custom $lookup operator(s) to this aggregate pipeline.

    Parameters:

    • options <Object> to $lookup as described in the above link

    Returns:

    See:

    Examples:

    1. aggregate.lookup({ from: 'users', localField: 'userId', foreignField: '_id', as: 'users' });

    show code

    1. Aggregate.prototype.lookup = function(options) {
    2.   return this.append({$lookup: options});
    3. };

    Aggregate#match(arg)

    Appends a new custom $match operator to this aggregate pipeline.

    Parameters:

    • arg <Object> $match operator contents

    Returns:

    See:

    Examples:

    1. aggregate.match({ department: { $in: [ "sales", "engineering" ] } });

    Aggregate#model(model)

    Binds this aggregate to a model.

    Parameters:

    • model <Model> the model to which the aggregate is to be bound

    Returns:

    show code

    1. Aggregate.prototype.model = function(model) {
    2.   this._model = model;
    3.   if (model.schema != null) {
    4.     if (this.options.readPreference == null &&
    5.         model.schema.options.read != null) {
    6.       this.options.readPreference = model.schema.options.read;
    7.     }
    8.     if (this.options.collation == null &&
    9.         model.schema.options.collation != null) {
    10.       this.options.collation = model.schema.options.collation;
    11.     }
    12.   }
    13.   return this;
    14. };

    Aggregate#near(parameters)

    Appends a new $geoNear operator to this aggregate pipeline.

    Parameters:

    Returns:

    See:

    NOTE:

    MUST be used as the first operator in the pipeline.

    Examples:

    1. aggregate.near({
    2.   near: [40.724, -73.997],
    3.   distanceField: "dist.calculated", // required
    4.   maxDistance: 0.008,
    5.   query: { type: "public" },
    6.   includeLocs: "dist.location",
    7.   uniqueDocs: true,
    8.   num: 5
    9. });

    Aggregate#option(options, number, boolean, object)

    Lets you set arbitrary options, for middleware or plugins.

    Parameters:

    Returns:

    See:

    Example:

    1. var agg = Model.aggregate(..).option({ allowDiskUse: true }); // Set the `allowDiskUse` option
    2. agg.options; // `{ allowDiskUse: true }`

    show code

    1. Aggregate.prototype.option = function(value) {
    2.   for (var key in value) {
    3.     this.options[key] = value[key];
    4.   }
    5.   return this;
    6. };

    Aggregate#pipeline()

    Returns the current pipeline

    Returns:

    Example:

    1. MyModel.aggregate().match({ test: 1 }).pipeline(); // [{ $match: { test: 1 } }]

    show code

    1. Aggregate.prototype.pipeline = function() {
    2.   return this._pipeline;
    3. };

    Aggregate#project(arg)

    Appends a new $project operator to this aggregate pipeline.

    Parameters:

    Returns:

    See:

    Mongoose query selection syntax is also supported.

    Examples:

    1. // include a, include b, exclude _id
    2. aggregate.project("a b -_id");
    4. // or you may use object notation, useful when
    5. // you have keys already prefixed with a "-"
    6. aggregate.project({a: 1, b: 1, _id: 0});
    8. // reshaping documents
    9. aggregate.project({
    10.     newField: '$b.nested'
    11.   , plusTen: { $add: ['$val', 10]}
    12.   , sub: {
    13.        name: '$a'
    14.     }
    15. })
    17. // etc
    18. aggregate.project({ salary_k: { $divide: [ "$salary", 1000 ] } });

    show code

    1. Aggregate.prototype.project = function(arg) {
    2.   var fields = {};
    4.   if (typeof arg === 'object' && !util.isArray(arg)) {
    5.     Object.keys(arg).forEach(function(field) {
    6.       fields[field] = arg[field];
    7.     });
    8.   } else if (arguments.length === 1 && typeof arg === 'string') {
    9.     arg.split(/\s+/).forEach(function(field) {
    10.       if (!field) {
    11.         return;
    12.       }
    13.       var include = field[0] === '-' ? 0 : 1;
    14.       if (include === 0) {
    15.         field = field.substring(1);
    16.       }
    17.       fields[field] = include;
    18.     });
    19.   } else {
    20.     throw new Error('Invalid project() argument. Must be string or object');
    21.   }
    23.   return this.append({$project: fields});
    24. };

    Aggregate#read(pref, [tags])

    Sets the readPreference option for the aggregation query.

    Parameters:

    • pref <String> one of the listed preference options or their aliases
    • [tags] <Array> optional tags for this query

    See:

    Example:

    1. Model.aggregate(..).read('primaryPreferred').exec(callback)

    show code

    1. Aggregate.prototype.read = function(pref, tags) {
    2.   if (!this.options) {
    3.     this.options = {};
    4.   }
    5.   read.call(this, pref, tags);
    6.   return this;
    7. };

    Aggregate#sample(size)

    Appepnds new custom $sample operator(s) to this aggregate pipeline.

    Parameters:

    • size <Number> number of random documents to pick

    Returns:

    See:

    Examples:

    1. aggregate.sample(3); // Add a pipeline that picks 3 random documents

    show code

    1. Aggregate.prototype.sample = function(size) {
    2.   return this.append({$sample: {size: size}});
    3. };

    Aggregate#skip(num)

    Appends a new $skip operator to this aggregate pipeline.

    Parameters:

    • num <Number> number of records to skip before next stage

    Returns:

    See:

    Examples:

    1. aggregate.skip(10);

    Aggregate#sort(arg)

    Appends a new $sort operator to this aggregate pipeline.

    Parameters:

    Returns:

    See:

    If an object is passed, values allowed are asc, desc, ascending, descending, 1, and -1.

    If a string is passed, it must be a space delimited list of path names. The sort order of each path is ascending unless the path name is prefixed with - which will be treated as descending.

    Examples:

    1. // these are equivalent
    2. aggregate.sort({ field: 'asc', test: -1 });
    3. aggregate.sort('field -test');

    show code

    1. Aggregate.prototype.sort = function(arg) {
    2.   // TODO refactor to reuse the query builder logic
    4.   var sort = {};
    6.   if (arg.constructor.name === 'Object') {
    7.     var desc = ['desc', 'descending', -1];
    8.     Object.keys(arg).forEach(function(field) {
    9.       // If sorting by text score, skip coercing into 1/-1
    10.       if (arg[field] instanceof Object && arg[field].$meta) {
    11.         sort[field] = arg[field];
    12.         return;
    13.       }
    14.       sort[field] = desc.indexOf(arg[field]) === -1 ? 1 : -1;
    15.     });
    16.   } else if (arguments.length === 1 && typeof arg === 'string') {
    17.     arg.split(/\s+/).forEach(function(field) {
    18.       if (!field) {
    19.         return;
    20.       }
    21.       var ascend = field[0] === '-' ? -1 : 1;
    22.       if (ascend === -1) {
    23.         field = field.substring(1);
    24.       }
    25.       sort[field] = ascend;
    26.     });
    27.   } else {
    28.     throw new TypeError('Invalid sort() argument. Must be a string or object.');
    29.   }
    31.   return this.append({$sort: sort});
    32. };

    Aggregate#then([resolve], [reject])

    Provides promise for aggregate.

    Parameters:

    Returns:

    See:

    Example:

    1. Model.aggregate(..).then(successCallback, errorCallback);

    show code

    1. Aggregate.prototype.then = function(resolve, reject) {
    2.   return this.exec().then(resolve, reject);
    3. };

    Aggregate#unwind(fields)

    Appends new custom $unwind operator(s) to this aggregate pipeline.

    Parameters:

    • fields <String> the field(s) to unwind

    Returns:

    See:

    Note that the $unwind operator requires the path name to start with ‘$’.
    Mongoose will prepend ‘$’ if the specified field doesn’t start ‘$’.

    Examples:

    1. aggregate.unwind("tags");
    2. aggregate.unwind("a", "b", "c");

    show code

    1. Aggregate.prototype.unwind = function() {
    2.   var args = utils.args(arguments);
    4.   var res = [];
    5.   for (var i = 0; i < args.length; ++i) {
    6.     var arg = args[i];
    7.     if (arg && typeof arg === 'object') {
    8.       res.push({ $unwind: arg });
    9.     } else if (typeof arg === 'string') {
    10.       res.push({
    11.         $unwind: (arg && arg.charAt(0) === '$') ? arg : '$' + arg
    12.       });
    13.     } else {
    14.       throw new Error('Invalid arg "' + arg + '" to unwind(), ' +
    15.         'must be string or object');
    16.     }
    17.   }
    19.   return this.append.apply(this, res);
    20. };

  • ES6Promise.js

    ES6Promise(fn)

    ES6 Promise wrapper constructor.

    Parameters:

    • fn <Function> a function which will be called when the promise is resolved that accepts fn(err, ...){} as signature

    Promises are returned from executed queries. Example:

    1. var query = Candy.find({ bar: true });
    2. var promise = query.exec();

    DEPRECATED. Mongoose 5.0 will use native promises by default (or bluebird,
    if native promises are not present) but still
    support plugging in your own ES6-compatible promises library. Mongoose 5.0
    will not support mpromise.

    show code

    1. function ES6Promise() {
    2.   throw new Error('Can\'t use ES6 promise with mpromise style constructor');
    3. }
    5. ES6Promise.use = function(Promise) {
    6.   ES6Promise.ES6 = Promise;
    7. };
    9. module.exports = ES6Promise;

  • utils.js

    exports.each(arr, fn)

    Executes a function on each element of an array (like _.each)

    show code

    1. exports.each = function(arr, fn) {
    2.   for (var i = 0; i < arr.length; ++i) {
    3.     fn(arr[i]);
    4.   }
    5. };

    Parameters:

    exports.mergeClone(to, fromObj)

    merges to with a copy of from

    show code

    1. exports.mergeClone = function(to, fromObj) {
    2.   var keys = Object.keys(fromObj);
    3.   var len = keys.length;
    4.   var i = 0;
    5.   var key;
    7.   while (i < len) {
    8.     key = keys[i++];
    9.     if (typeof to[key] === 'undefined') {
    10.       // make sure to retain key order here because of a bug handling the $each
    11.       // operator in mongodb 2.4.4
    12.       to[key] = exports.clone(fromObj[key], {
    13.         retainKeyOrder: 1,
    14.         flattenDecimals: false
    15.       });
    16.     } else {
    17.       if (exports.isObject(fromObj[key])) {
    18.         var obj = fromObj[key];
    19.         if (isMongooseObject(fromObj[key]) && !fromObj[key].isMongooseBuffer) {
    20.           obj = obj.toObject({ transform: false, virtuals: false });
    21.         }
    22.         if (fromObj[key].isMongooseBuffer) {
    23.           obj = new Buffer(obj);
    24.         }
    25.         exports.mergeClone(to[key], obj);
    26.       } else {
    27.         // make sure to retain key order here because of a bug handling the
    28.         // $each operator in mongodb 2.4.4
    29.         to[key] = exports.clone(fromObj[key], {
    30.           retainKeyOrder: 1,
    31.           flattenDecimals: false
    32.         });
    33.       }
    34.     }
    35.   }
    36. };

    Parameters:

    exports.pluralization

    Pluralization rules.

    show code

    1. exports.pluralization = [
    2.   [/(m)an$/gi, '$1en'],
    3.   [/(pe)rson$/gi, '$1ople'],
    4.   [/(child)$/gi, '$1ren'],
    5.   [/^(ox)$/gi, '$1en'],
    6.   [/(ax|test)is$/gi, '$1es'],
    7.   [/(octop|vir)us$/gi, '$1i'],
    8.   [/(alias|status)$/gi, '$1es'],
    9.   [/(bu)s$/gi, '$1ses'],
    10.   [/(buffal|tomat|potat)o$/gi, '$1oes'],
    11.   [/([ti])um$/gi, '$1a'],
    12.   [/sis$/gi, 'ses'],
    13.   [/(?:([^f])fe|([lr])f)$/gi, '$1$2ves'],
    14.   [/(hive)$/gi, '$1s'],
    15.   [/([^aeiouy]|qu)y$/gi, '$1ies'],
    16.   [/(x|ch|ss|sh)$/gi, '$1es'],
    17.   [/(matr|vert|ind)ix|ex$/gi, '$1ices'],
    18.   [/([m|l])ouse$/gi, '$1ice'],
    19.   [/(kn|w|l)ife$/gi, '$1ives'],
    20.   [/(quiz)$/gi, '$1zes'],
    21.   [/s$/gi, 's'],
    22.   [/([^a-z])$/, '$1'],
    23.   [/$/gi, 's']
    24. ];
    25. var rules = exports.pluralization;

    These rules are applied while processing the argument to toCollectionName.

    exports.uncountables

    Uncountable words.

    show code

    1. exports.uncountables = [
    2.   'advice',
    3.   'energy',
    4.   'excretion',
    5.   'digestion',
    6.   'cooperation',
    7.   'health',
    8.   'justice',
    9.   'labour',
    10.   'machinery',
    11.   'equipment',
    12.   'information',
    13.   'pollution',
    14.   'sewage',
    15.   'paper',
    16.   'money',
    17.   'species',
    18.   'series',
    19.   'rain',
    20.   'rice',
    21.   'fish',
    22.   'sheep',
    23.   'moose',
    24.   'deer',
    25.   'news',
    26.   'expertise',
    27.   'status',
    28.   'media'
    29. ];
    30. var uncountables = exports.uncountables;

    These words are applied while processing the argument to toCollectionName.

  • browser.js

    function Object() { [native code] }#Promise()%20%7B%20%5Bnative%20code%5D%20%7D-Promise)

    The Mongoose Promise constructor.

    exports.Document()

    The Mongoose browser Document constructor.

    exports.Error()

    The MongooseError constructor.

    exports.PromiseProvider()

    Storage layer for mongoose promises

    exports.Schema()

    The Mongoose Schema constructor

    Example:

    1. var mongoose = require('mongoose');
    2. var Schema = mongoose.Schema;
    3. var CatSchema = new Schema(..);

    exports.VirtualType()

    The Mongoose VirtualType constructor

    exports#SchemaTypes

    The various Mongoose SchemaTypes.

    Note:

    Alias of mongoose.Schema.Types for backwards compatibility.

    show code

    1. exports.SchemaType = require('./schematype.js');

    See:

    exports#Types

    The various Mongoose Types.

    Example:

    1. var mongoose = require('mongoose');
    2. var array = mongoose.Types.Array;

    Types:

    Using this exposed access to the ObjectId type, we can construct ids on demand.

    1. var ObjectId = mongoose.Types.ObjectId;
    2. var id1 = new ObjectId;

    show code

    1. exports.Types = require('./types');

    exports#utils

    Internal utils

    show code

    1. exports.utils = require('./utils.js');

  • promise.js

    Promise#addBack(listener)

    Adds a single function as a listener to both err and complete.

    Parameters:

    Returns:

    It will be executed with traditional node.js argument position when the promise is resolved.

    1. promise.addBack(function (err, args...) {
    2.   if (err) return handleError(err);
    3.   console.log('success');
    4. })

    Alias of mpromise#onResolve.

    Deprecated. Use onResolve instead.

    Promise#addCallback(listener)

    Adds a listener to the complete (success) event.

    Parameters:

    Returns:

    Alias of mpromise#onFulfill.

    Deprecated. Use onFulfill instead.

    Promise#addErrback(listener)

    Adds a listener to the err (rejected) event.

    Parameters:

    Returns:

    Alias of mpromise#onReject.

    Deprecated. Use onReject instead.

    Promise#catch(onReject)

    ES6-style .catch() shorthand

    Parameters:

    Returns:

    Promise#end()

    Signifies that this promise was the last in a chain of then()s: if a handler passed to the call to then which produced this promise throws, the exception will go uncaught.

    See:

    Example:

    1. var p = new Promise;
    2. p.then(function(){ throw new Error('shucks') });
    3. setTimeout(function () {
    4.   p.fulfill();
    5.   // error was caught and swallowed by the promise returned from
    6.   // p.then(). we either have to always register handlers on
    7.   // the returned promises or we can do the following...
    8. }, 10);
    10. // this time we use .end() which prevents catching thrown errors
    11. var p = new Promise;
    12. var p2 = p.then(function(){ throw new Error('shucks') }).end(); // &lt;--
    13. setTimeout(function () {
    14.   p.fulfill(); // throws "shucks"
    15. }, 10);

    Promise#error(err)

    Rejects this promise with err.

    Parameters:

    Returns:

    If the promise has already been fulfilled or rejected, not action is taken.

    Differs from #reject by first casting err to an Error if it is not instanceof Error.

    show code

    1. Promise.prototype.error = function(err) {
    2.   if (!(err instanceof Error)) {
    3.     if (err instanceof Object) {
    4.       err = util.inspect(err);
    5.     }
    6.     err = new Error(err);
    7.   }
    8.   return this.reject(err);
    9. };

    Promise#on(event, listener)

    Adds listener to the event.

    Parameters:

    Returns:

    See:

    If event is either the success or failure event and the event has already been emitted, thelistener is called immediately and passed the results of the original emitted event.

    Promise(fn)

    Promise constructor.

    Parameters:

    • fn <Function> a function which will be called when the promise is resolved that accepts fn(err, ...){} as signature

    Inherits:

    Events:

    • err: Emits when the promise is rejected

    • complete: Emits when the promise is fulfilled

    Promises are returned from executed queries. Example:

    1. var query = Candy.find({ bar: true });
    2. var promise = query.exec();

    DEPRECATED. Mongoose 5.0 will use native promises by default (or bluebird,
    if native promises are not present) but still
    support plugging in your own ES6-compatible promises library. Mongoose 5.0
    will not support mpromise.

    show code

    1. function Promise(fn) {
    2.   MPromise.call(this, fn);
    3. }

    Promise#reject(reason)

    Rejects this promise with reason.

    Parameters:

    Returns:

    See:

    If the promise has already been fulfilled or rejected, not action is taken.

    Promise#resolve([err], [val])

    Resolves this promise to a rejected state if err is passed or a fulfilled state if no err is passed.

    Parameters:

    • [err] <Error> error or null
    • [val] <Object> value to fulfill the promise with

    If the promise has already been fulfilled or rejected, not action is taken.

    err will be cast to an Error if not already instanceof Error.

    NOTE: overrides mpromise#resolve to provide error casting.

    show code

    1. Promise.prototype.resolve = function(err) {
    2.   if (err) return this.error(err);
    3.   return this.fulfill.apply(this, Array.prototype.slice.call(arguments, 1));
    4. };

    Promise#then(onFulFill, onReject)

    Creates a new promise and returns it. If onFulfill or onReject are passed, they are added as SUCCESS/ERROR callbacks to this promise after the nextTick.

    Parameters:

    Returns:

    See:

    Conforms to promises/A+ specification.

    Example:

    1. var promise = Meetups.find({ tags: 'javascript' }).select('_id').exec();
    2. promise.then(function (meetups) {
    3.   var ids = meetups.map(function (m) {
    4.     return m._id;
    5.   });
    6.   return People.find({ meetups: { $in: ids } }).exec();
    7. }).then(function (people) {
    8.   if (people.length &lt; 10000) {
    9.     throw new Error('Too few people!!!');
    10.   } else {
    11.     throw new Error('Still need more people!!!');
    12.   }
    13. }).then(null, function (err) {
    14.   assert.ok(err instanceof Error);
    15. });

    Promise.complete(args)

    Fulfills this promise with passed arguments.

    Parameters:

    • args <T>

    Alias of mpromise#fulfill.

    Deprecated. Use fulfill instead.

    Promise.ES6(resolver)

    ES6-style promise constructor wrapper around mpromise.

    show code

    1. Promise.ES6 = function(resolver) {
    2.   var promise = new Promise();
    4.   // No try/catch for backwards compatibility
    5.   resolver(
    6.     function() {
    7.       promise.complete.apply(promise, arguments);
    8.     },
    9.     function(e) {
    10.       promise.error(e);
    11.     });
    13.   return promise;
    14. };

    Parameters:

    Returns:

    Promise.fulfill(args)

    Fulfills this promise with passed arguments.

    Parameters:

    • args <T>

    See:

  • schematype.js

    SchemaType#applyGetters(value, scope)

    Applies getters to a value

    Parameters:

    show code

    1. SchemaType.prototype.applyGetters = function(value, scope) {
    2.   var v = value,
    3.       getters = this.getters,
    4.       len = getters.length;
    6.   if (!len) {
    7.     return v;
    8.   }
    10.   while (len--) {
    11.     v = getters[len].call(scope, v, this);
    12.   }
    14.   return v;
    15. };

    SchemaType#applySetters(value, scope, init)

    Applies setters

    Parameters:

    show code

    1. SchemaType.prototype.applySetters = function(value, scope, init, priorVal, options) {
    2.   var v = this._applySetters(value, scope, init, priorVal, options);
    4.   if (v == null) {
    5.     return v;
    6.   }
    8.   // do not cast until all setters are applied #665
    9.   v = this.cast(v, scope, init, priorVal, options);
    11.   return v;
    12. };

    SchemaType#castForQuery([$conditional], val)

    Cast the given value with the given optional query operator.

    Parameters:

    • [$conditional] <String> query operator, like $eq or $in
    • val <T>

    show code

    1. SchemaType.prototype.castForQuery = function($conditional, val) {
    2.   var handler;
    3.   if (arguments.length === 2) {
    4.     handler = this.$conditionalHandlers[$conditional];
    5.     if (!handler) {
    6.       throw new Error('Can\'t use ' + $conditional);
    7.     }
    8.     return handler.call(this, val);
    9.   }
    10.   val = $conditional;
    11.   return this._castForQuery(val);
    12. };

    SchemaType#checkRequired(val)

    Default check for if this path satisfies the required validator.

    Parameters:

    • val <T>

    show code

    1. SchemaType.prototype.checkRequired = function(val) {
    2.   return val != null;
    3. };

    SchemaType#default(val)

    Sets a default value for this SchemaType.

    Parameters:

    Returns:

    Example:

    1. var schema = new Schema({ n: { type: Number, default: 10 })
    2. var M = db.model('M', schema)
    3. var m = new M;
    4. console.log(m.n) // 10

    Defaults can be either functions which return the value to use as the default or the literal value itself. Either way, the value will be cast based on its schema type before being set during document creation.

    Example:

    1. // values are cast:
    2. var schema = new Schema({ aNumber: { type: Number, default: 4.815162342 }})
    3. var M = db.model('M', schema)
    4. var m = new M;
    5. console.log(m.aNumber) // 4.815162342
    7. // default unique objects for Mixed types:
    8. var schema = new Schema({ mixed: Schema.Types.Mixed });
    9. schema.path('mixed').default(function () {
    10.   return {};
    11. });
    13. // if we don't use a function to return object literals for Mixed defaults,
    14. // each document will receive a reference to the same object literal creating
    15. // a "shared" object instance:
    16. var schema = new Schema({ mixed: Schema.Types.Mixed });
    17. schema.path('mixed').default({});
    18. var M = db.model('M', schema);
    19. var m1 = new M;
    20. m1.mixed.added = 1;
    21. console.log(m1.mixed); // { added: 1 }
    22. var m2 = new M;
    23. console.log(m2.mixed); // { added: 1 }

    show code

    1. SchemaType.prototype.default = function(val) {
    2.   if (arguments.length === 1) {
    3.     if (val === void 0) {
    4.       this.defaultValue = void 0;
    5.       return void 0;
    6.     }
    7.     this.defaultValue = val;
    8.     return this.defaultValue;
    9.   } else if (arguments.length > 1) {
    10.     this.defaultValue = utils.args(arguments);
    11.   }
    12.   return this.defaultValue;
    13. };

    SchemaType#doValidate(value, callback, scope)

    Performs a validation of value using the validators declared for this SchemaType.

    Parameters:

    show code

    1. SchemaType.prototype.doValidate = function(value, fn, scope) {
    2.   var err = false;
    3.   var path = this.path;
    4.   var count = this.validators.length;
    6.   if (!count) {
    7.     return fn(null);
    8.   }
    10.   var validate = function(ok, validatorProperties) {
    11.     if (err) {
    12.       return;
    13.     }
    14.     if (ok === undefined || ok) {
    15.       --count || fn(null);
    16.     } else {
    17.       var ErrorConstructor = validatorProperties.ErrorConstructor || ValidatorError;
    18.       err = new ErrorConstructor(validatorProperties);
    19.       err.$isValidatorError = true;
    20.       fn(err);
    21.     }
    22.   };
    24.   var _this = this;
    25.   this.validators.forEach(function(v) {
    26.     if (err) {
    27.       return;
    28.     }
    30.     var validator = v.validator;
    31.     var ok;
    33.     var validatorProperties = utils.clone(v);
    34.     validatorProperties.path = path;
    35.     validatorProperties.value = value;
    37.     if (validator instanceof RegExp) {
    38.       validate(validator.test(value), validatorProperties);
    39.     } else if (typeof validator === 'function') {
    40.       if (value === undefined && validator !== _this.requiredValidator) {
    41.         validate(true, validatorProperties);
    42.         return;
    43.       }
    44.       if (validatorProperties.isAsync) {
    45.         asyncValidate(validator, scope, value, validatorProperties, validate);
    46.       } else if (validator.length === 2 && !('isAsync' in validatorProperties)) {
    47.         legacyAsyncValidate(validator, scope, value, validatorProperties,
    48.           validate);
    49.       } else {
    50.         try {
    51.           ok = validator.call(scope, value);
    52.         } catch (error) {
    53.           ok = false;
    54.           validatorProperties.reason = error;
    55.         }
    56.         if (ok && typeof ok.then === 'function') {
    57.           ok.then(
    58.             function(ok) { validate(ok, validatorProperties); },
    59.             function(error) {
    60.               validatorProperties.reason = error;
    61.               ok = false;
    62.               validate(ok, validatorProperties);
    63.             });
    64.         } else {
    65.           validate(ok, validatorProperties);
    66.         }
    67.       }
    68.     }
    69.   });
    70. };

    SchemaType#doValidateSync(value, scope)

    Performs a validation of value using the validators declared for this SchemaType.

    Parameters:

    Returns:

    Note:

    This method ignores the asynchronous validators.

    show code

    1. SchemaType.prototype.doValidateSync = function(value, scope) {
    2.   var err = null,
    3.       path = this.path,
    4.       count = this.validators.length;
    6.   if (!count) {
    7.     return null;
    8.   }
    10.   var validate = function(ok, validatorProperties) {
    11.     if (err) {
    12.       return;
    13.     }
    14.     if (ok !== undefined && !ok) {
    15.       var ErrorConstructor = validatorProperties.ErrorConstructor || ValidatorError;
    16.       err = new ErrorConstructor(validatorProperties);
    17.       err.$isValidatorError = true;
    18.     }
    19.   };
    21.   var validators = this.validators;
    22.   if (value === void 0) {
    23.     if (this.validators.length > 0 && this.validators[0].type === 'required') {
    24.       validators = [this.validators[0]];
    25.     } else {
    26.       return null;
    27.     }
    28.   }
    30.   validators.forEach(function(v) {
    31.     if (err) {
    32.       return;
    33.     }
    35.     var validator = v.validator;
    36.     var validatorProperties = utils.clone(v);
    37.     validatorProperties.path = path;
    38.     validatorProperties.value = value;
    39.     var ok;
    41.     if (validator instanceof RegExp) {
    42.       validate(validator.test(value), validatorProperties);
    43.     } else if (typeof validator === 'function') {
    44.       // if not async validators
    45.       if (validator.length !== 2 && !validatorProperties.isAsync) {
    46.         try {
    47.           ok = validator.call(scope, value);
    48.         } catch (error) {
    49.           ok = false;
    50.           validatorProperties.reason = error;
    51.         }
    52.         validate(ok, validatorProperties);
    53.       }
    54.     }
    55.   });
    57.   return err;
    58. };

    SchemaType#get(fn)

    Adds a getter to this schematype.

    Parameters:

    Returns:

    Example:

    1. function dob (val) {
    2.   if (!val) return val;
    3.   return (val.getMonth() + 1) + "/" + val.getDate() + "/" + val.getFullYear();
    4. }
    6. // defining within the schema
    7. var s = new Schema({ born: { type: Date, get: dob })
    9. // or by retreiving its SchemaType
    10. var s = new Schema({ born: Date })
    11. s.path('born').get(dob)

    Getters allow you to transform the representation of the data as it travels from the raw mongodb document to the value that you see.

    Suppose you are storing credit card numbers and you want to hide everything except the last 4 digits to the mongoose user. You can do so by defining a getter in the following way:

    1. function obfuscate (cc) {
    2.   return '****-****-****-' + cc.slice(cc.length-4, cc.length);
    3. }
    5. var AccountSchema = new Schema({
    6.   creditCardNumber: { type: String, get: obfuscate }
    7. });
    9. var Account = db.model('Account', AccountSchema);
    11. Account.findById(id, function (err, found) {
    12.   console.log(found.creditCardNumber); // '****-****-****-1234'
    13. });

    Getters are also passed a second argument, the schematype on which the getter was defined. This allows for tailored behavior based on options passed in the schema.

    1. function inspector (val, schematype) {
    2.   if (schematype.options.required) {
    3.     return schematype.path + ' is required';
    4.   } else {
    5.     return schematype.path + ' is not';
    6.   }
    7. }
    9. var VirusSchema = new Schema({
    10.   name: { type: String, required: true, get: inspector },
    11.   taxonomy: { type: String, get: inspector }
    12. })
    14. var Virus = db.model('Virus', VirusSchema);
    16. Virus.findById(id, function (err, virus) {
    17.   console.log(virus.name);     // name is required
    18.   console.log(virus.taxonomy); // taxonomy is not
    19. })

    show code

    1. SchemaType.prototype.get = function(fn) {
    2.   if (typeof fn !== 'function') {
    3.     throw new TypeError('A getter must be a function.');
    4.   }
    5.   this.getters.push(fn);
    6.   return this;
    7. };

    SchemaType#getDefault(scope, init)

    Gets the default value

    Parameters:

    • scope <Object> the scope which callback are executed
    • init <Boolean>

    show code

    1. SchemaType.prototype.getDefault = function(scope, init) {
    2.   var ret = typeof this.defaultValue === 'function'
    3.       ? this.defaultValue.call(scope)
    4.       : this.defaultValue;
    6.   if (ret !== null && ret !== undefined) {
    7.     if (typeof ret === 'object' && (!this.options || !this.options.shared)) {
    8.       ret = utils.clone(ret, { retainKeyOrder: true });
    9.     }
    11.     var casted = this.cast(ret, scope, init);
    12.     if (casted && casted.$isSingleNested) {
    13.       casted.$parent = scope;
    14.     }
    15.     return casted;
    16.   }
    17.   return ret;
    18. };

    SchemaType#index(options)

    Declares the index options for this schematype.

    Parameters:

    Returns:

    Example:

    1. var s = new Schema({ name: { type: String, index: true })
    2. var s = new Schema({ loc: { type: [Number], index: 'hashed' })
    3. var s = new Schema({ loc: { type: [Number], index: '2d', sparse: true })
    4. var s = new Schema({ loc: { type: [Number], index: { type: '2dsphere', sparse: true }})
    5. var s = new Schema({ date: { type: Date, index: { unique: true, expires: '1d' }})
    6. Schema.path('my.path').index(true);
    7. Schema.path('my.date').index({ expires: 60 });
    8. Schema.path('my.path').index({ unique: true, sparse: true });

    NOTE:

    Indexes are created in the background by default. Specify background: false to override.

    Direction doesn’t matter for single key indexes

    show code

    1. SchemaType.prototype.index = function(options) {
    2.   this._index = options;
    3.   utils.expires(this._index);
    4.   return this;
    5. };

    SchemaType#required(required, [options.isRequired], [options.ErrorConstructor], [message])

    Adds a required validator to this SchemaType. The validator gets added
    to the front of this SchemaType’s validators array using unshift().

    Parameters:

    • required <Boolean, Function, Object> enable/disable the validator, or function that returns required boolean, or options object
    • [options.isRequired] <Boolean, Function> enable/disable the validator, or function that returns required boolean
    • [options.ErrorConstructor] <Function> custom error constructor. The constructor receives 1 parameter, an object containing the validator properties.
    • [message] <String> optional custom error message

    Returns:

    See:

    Example:

    1. var s = new Schema({ born: { type: Date, required: true })
    3. // or with custom error message
    5. var s = new Schema({ born: { type: Date, required: '{PATH} is required!' })
    7. // or with a function
    9. var s = new Schema({
    10.   userId: ObjectId,
    11.   username: {
    12.     type: String,
    13.     required: function() { return this.userId != null; }
    14.   }
    15. })
    17. // or with a function and a custom message
    18. var s = new Schema({
    19.   userId: ObjectId,
    20.   username: {
    21.     type: String,
    22.     required: [
    23.       function() { return this.userId != null; },
    24.       'username is required if id is specified'
    25.     ]
    26.   }
    27. })
    29. // or through the path API
    31. Schema.path('name').required(true);
    33. // with custom error messaging
    35. Schema.path('name').required(true, 'grrr :( ');
    37. // or make a path conditionally required based on a function
    38. var isOver18 = function() { return this.age &gt;= 18; };
    39. Schema.path('voterRegistrationId').required(isOver18);

    The required validator uses the SchemaType’s checkRequired function to
    determine whether a given value satisfies the required validator. By default,
    a value satisfies the required validator if val != null (that is, if
    the value is not null nor undefined). However, most built-in mongoose schema
    types override the default checkRequired function:

    show code

    1. SchemaType.prototype.required = function(required, message) {
    2.   var customOptions = {};
    3.   if (typeof required === 'object') {
    4.     customOptions = required;
    5.     message = customOptions.message || message;
    6.     required = required.isRequired;
    7.   }
    9.   if (required === false) {
    10.     this.validators = this.validators.filter(function(v) {
    11.       return v.validator !== this.requiredValidator;
    12.     }, this);
    14.     this.isRequired = false;
    15.     return this;
    16.   }
    18.   var _this = this;
    19.   this.isRequired = true;
    21.   this.requiredValidator = function(v) {
    22.     // in here, `this` refers to the validating document.
    23.     // no validation when this path wasn't selected in the query.
    24.     if ('isSelected' in this && !this.isSelected(_this.path) && !this.isModified(_this.path)) {
    25.       return true;
    26.     }
    28.     return ((typeof required === 'function') && !required.apply(this)) ||
    29.         _this.checkRequired(v, this);
    30.   };
    31.   this.originalRequiredValue = required;
    33.   if (typeof required === 'string') {
    34.     message = required;
    35.     required = undefined;
    36.   }
    38.   var msg = message || MongooseError.messages.general.required;
    39.   this.validators.unshift(utils.assign({}, customOptions, {
    40.     validator: this.requiredValidator,
    41.     message: msg,
    42.     type: 'required'
    43.   }));
    45.   return this;
    46. };

    SchemaType(path, [options], [instance])

    SchemaType constructor

    Parameters:

    show code

    1. function SchemaType(path, options, instance) {
    2.   this.path = path;
    3.   this.instance = instance;
    4.   this.validators = [];
    5.   this.setters = [];
    6.   this.getters = [];
    7.   this.options = options;
    8.   this._index = null;
    9.   this.selected;
    11.   for (var prop in options) {
    12.     if (this[prop] && typeof this[prop] === 'function') {
    13.       // { unique: true, index: true }
    14.       if (prop === 'index' && this._index) {
    15.         continue;
    16.       }
    18.       var val = options[prop];
    19.       // Special case so we don't screw up array defaults, see gh-5780
    20.       if (prop === 'default') {
    21.         this.default(val);
    22.         continue;
    23.       }
    25.       var opts = Array.isArray(val) ? val : [val];
    27.       this[prop].apply(this, opts);
    28.     }
    29.   }
    31.   Object.defineProperty(this, '$$context', {
    32.     enumerable: false,
    33.     configurable: false,
    34.     writable: true,
    35.     value: null
    36.   });
    37. }

    SchemaType#select(val)

    Sets default select() behavior for this path.

    Parameters:

    Returns:

    Set to true if this path should always be included in the results, false if it should be excluded by default. This setting can be overridden at the query level.

    Example:

    1. T = db.model('T', new Schema({ x: { type: String, select: true }}));
    2. T.find(..); // field x will always be selected ..
    3. // .. unless overridden;
    4. T.find().select('-x').exec(callback);

    show code

    1. SchemaType.prototype.select = function select(val) {
    2.   this.selected = !!val;
    3.   return this;
    4. };

    SchemaType#set(fn)

    Adds a setter to this schematype.

    Parameters:

    Returns:

    Example:

    1. function capitalize (val) {
    2.   if (typeof val !== 'string') val = '';
    3.   return val.charAt(0).toUpperCase() + val.substring(1);
    4. }
    6. // defining within the schema
    7. var s = new Schema({ name: { type: String, set: capitalize }})
    9. // or by retreiving its SchemaType
    10. var s = new Schema({ name: String })
    11. s.path('name').set(capitalize)

    Setters allow you to transform the data before it gets to the raw mongodb document and is set as a value on an actual key.

    Suppose you are implementing user registration for a website. Users provide an email and password, which gets saved to mongodb. The email is a string that you will want to normalize to lower case, in order to avoid one email having more than one account — e.g., otherwise, avenue@q.com can be registered for 2 accounts via avenue@q.com and AvEnUe@Q.CoM.

    You can set up email lower case normalization easily via a Mongoose setter.

    1. function toLower(v) {
    2.   return v.toLowerCase();
    3. }
    5. var UserSchema = new Schema({
    6.   email: { type: String, set: toLower }
    7. });
    9. var User = db.model('User', UserSchema);
    11. var user = new User({email: 'AVENUE@Q.COM'});
    12. console.log(user.email); // 'avenue@q.com'
    14. // or
    15. var user = new User();
    16. user.email = 'Avenue@Q.com';
    17. console.log(user.email); // 'avenue@q.com'

    As you can see above, setters allow you to transform the data before it stored in MongoDB.

    NOTE: setters by default do not run on queries by default.

    1. // Will **not** run the `toLower()` setter by default.
    2. User.updateOne({ _id: _id }, { $set: { email: 'AVENUE@Q.COM' } });

    Use the runSettersOnQuery option to opt-in to running setters on User.update():

    1. // Turn on `runSettersOnQuery` to run the setters from your schema.
    2. User.updateOne({ _id: _id }, { $set: { email: 'AVENUE@Q.COM' } }, {
    3.   runSettersOnQuery: true
    4. });

    NOTE: we could have also just used the built-in lowercase: true SchemaType option instead of defining our own function.

    1. new Schema({ email: { type: String, lowercase: true }})

    Setters are also passed a second argument, the schematype on which the setter was defined. This allows for tailored behavior based on options passed in the schema.

    1. function inspector (val, schematype) {
    2.   if (schematype.options.required) {
    3.     return schematype.path + ' is required';
    4.   } else {
    5.     return val;
    6.   }
    7. }
    9. var VirusSchema = new Schema({
    10.   name: { type: String, required: true, set: inspector },
    11.   taxonomy: { type: String, set: inspector }
    12. })
    14. var Virus = db.model('Virus', VirusSchema);
    15. var v = new Virus({ name: 'Parvoviridae', taxonomy: 'Parvovirinae' });
    17. console.log(v.name);     // name is required
    18. console.log(v.taxonomy); // Parvovirinae

    show code

    1. SchemaType.prototype.set = function(fn) {
    2.   if (typeof fn !== 'function') {
    3.     throw new TypeError('A setter must be a function.');
    4.   }
    5.   this.setters.push(fn);
    6.   return this;
    7. };

    SchemaType#sparse(bool)

    Declares a sparse index.

    Parameters:

    Returns:

    Example:

    1. var s = new Schema({ name: { type: String, sparse: true })
    2. Schema.path('name').index({ sparse: true });

    show code

    1. SchemaType.prototype.sparse = function(bool) {
    2.   if (this._index === null || this._index === undefined ||
    3.     typeof this._index === 'boolean') {
    4.     this._index = {};
    5.   } else if (typeof this._index === 'string') {
    6.     this._index = {type: this._index};
    7.   }
    9.   this._index.sparse = bool;
    10.   return this;
    11. };

    SchemaType#text(bool)

    Declares a full text index.

    Parameters:

    Returns:

    Example:

    1. var s = new Schema({name : {type: String, text : true })
    2.  Schema.path('name').index({text : true});

    show code

    1. SchemaType.prototype.text = function(bool) {
    2.   if (this._index === null || this._index === undefined ||
    3.     typeof this._index === 'boolean') {
    4.     this._index = {};
    5.   } else if (typeof this._index === 'string') {
    6.     this._index = {type: this._index};
    7.   }
    9.   this._index.text = bool;
    10.   return this;
    11. };

    SchemaType#unique(bool)

    Declares an unique index.

    Parameters:

    Returns:

    Example:

    1. var s = new Schema({ name: { type: String, unique: true }});
    2. Schema.path('name').index({ unique: true });

    NOTE: violating the constraint returns an E11000 error from MongoDB when saving, not a Mongoose validation error.

    show code

    1. SchemaType.prototype.unique = function(bool) {
    2.   if (this._index === false) {
    3.     if (!bool) {
    4.       return;
    5.     }
    6.     throw new Error('Path "' + this.path + '" may not have `index` set to ' +
    7.       'false and `unique` set to true');
    8.   }
    9.   if (this._index == null || this._index === true) {
    10.     this._index = {};
    11.   } else if (typeof this._index === 'string') {
    12.     this._index = {type: this._index};
    13.   }
    15.   this._index.unique = bool;
    16.   return this;
    17. };

    SchemaType#validate(obj, [errorMsg], [type])

    Adds validator(s) for this document path.

    Parameters:

    Returns:

    Validators always receive the value to validate as their first argument and must return Boolean. Returning false means validation failed.

    The error message argument is optional. If not passed, the default generic error message template will be used.

    Examples:

    1. // make sure every value is equal to "something"
    2. function validator (val) {
    3.   return val == 'something';
    4. }
    5. new Schema({ name: { type: String, validate: validator }});
    7. // with a custom error message
    9. var custom = [validator, 'Uh oh, {PATH} does not equal "something".']
    10. new Schema({ name: { type: String, validate: custom }});
    12. // adding many validators at a time
    14. var many = [
    15.     { validator: validator, msg: 'uh oh' }
    16.   , { validator: anotherValidator, msg: 'failed' }
    17. ]
    18. new Schema({ name: { type: String, validate: many }});
    20. // or utilizing SchemaType methods directly:
    22. var schema = new Schema({ name: 'string' });
    23. schema.path('name').validate(validator, 'validation of `{PATH}` failed with value `{VALUE}`');

    Error message templates:

    From the examples above, you may have noticed that error messages support basic templating. There are a few other template keywords besides {PATH} and {VALUE} too. To find out more, details are available here

    Asynchronous validation:

    Passing a validator function that receives two arguments tells mongoose that the validator is an asynchronous validator. The first argument passed to the validator function is the value being validated. The second argument is a callback function that must called when you finish validating the value and passed either true or false to communicate either success or failure respectively.

    1. schema.path('name').validate({
    2.   isAsync: true,
    3.   validator: function (value, respond) {
    4.     doStuff(value, function () {
    5.       ...
    6.       respond(false); // validation failed
    7.     });
    8.   },
    9.   message: 'Custom error message!' // Optional
    10. });
    12. // Can also return a promise
    13. schema.path('name').validate({
    14.   validator: function (value) {
    15.     return new Promise(function (resolve, reject) {
    16.       resolve(false); // validation failed
    17.     });
    18.   }
    19. });

    You might use asynchronous validators to retreive other documents from the database to validate against or to meet other I/O bound validation needs.

    Validation occurs pre('save') or whenever you manually execute document#validate.

    If validation fails during pre('save') and no callback was passed to receive the error, an error event will be emitted on your Models associated db connection, passing the validation error object along.

    1. var conn = mongoose.createConnection(..);
    2. conn.on('error', handleError);
    4. var Product = conn.model('Product', yourSchema);
    5. var dvd = new Product(..);
    6. dvd.save(); // emits error on the `conn` above

    If you desire handling these errors at the Model level, attach an error listener to your Model and the event will instead be emitted there.

    1. // registering an error listener on the Model lets us handle errors more locally
    2. Product.on('error', handleError);

    show code

    1. SchemaType.prototype.validate = function(obj, message, type) {
    2.   if (typeof obj === 'function' || obj && utils.getFunctionName(obj.constructor) === 'RegExp') {
    3.     var properties;
    4.     if (message instanceof Object && !type) {
    5.       properties = utils.clone(message);
    6.       if (!properties.message) {
    7.         properties.message = properties.msg;
    8.       }
    9.       properties.validator = obj;
    10.       properties.type = properties.type || 'user defined';
    11.     } else {
    12.       if (!message) {
    13.         message = MongooseError.messages.general.default;
    14.       }
    15.       if (!type) {
    16.         type = 'user defined';
    17.       }
    18.       properties = {message: message, type: type, validator: obj};
    19.     }
    20.     this.validators.push(properties);
    21.     return this;
    22.   }
    24.   var i,
    25.       length,
    26.       arg;
    28.   for (i = 0, length = arguments.length; i < length; i++) {
    29.     arg = arguments[i];
    30.     if (!(arg && utils.getFunctionName(arg.constructor) === 'Object')) {
    31.       var msg = 'Invalid validator. Received (' + typeof arg + ') '
    32.           + arg
    33.           + '. See http://mongoosejs.com/docs/api.html#schematype_SchemaType-validate';
    35.       throw new Error(msg);
    36.     }
    37.     this.validate(arg.validator, arg);
    38.   }
    40.   return this;
    41. };

    SchemaType._isRef(self, value, doc, init)

    Determines if value is a valid Reference.

    show code

    1. SchemaType._isRef = function(self, value, doc, init) {
    2.   // fast path
    3.   var ref = init && self.options && self.options.ref;
    5.   if (!ref && doc && doc.$__fullPath) {
    6.     // checks for
    7.     // - this populated with adhoc model and no ref was set in schema OR
    8.     // - setting / pushing values after population
    9.     var path = doc.$__fullPath(self.path);
    10.     var owner = doc.ownerDocument ? doc.ownerDocument() : doc;
    11.     ref = owner.populated(path);
    12.   }
    14.   if (ref) {
    15.     if (value == null) {
    16.       return true;
    17.     }
    18.     if (!Buffer.isBuffer(value) &&  // buffers are objects too
    19.         value._bsontype !== 'Binary' // raw binary value from the db
    20.         && utils.isObject(value)    // might have deselected _id in population query
    21.     ) {
    22.       return true;
    23.     }
    24.   }
    26.   return false;
    27. };

    Parameters:

    Returns:

  • querystream.js

    QueryStream#__next()

    Pulls the next doc from the cursor.

    See:

    show code

    1. QueryStream.prototype.__next = function() {
    2.   if (this.paused || this._destroyed) {
    3.     this._running = false;
    4.     return this._running;
    5.   }
    7.   var _this = this;
    8.   _this._inline = T_INIT;
    10.   _this._cursor.nextObject(function cursorcb(err, doc) {
    11.     _this._onNextObject(err, doc);
    12.   });
    14.   // if onNextObject() was already called in this tick
    15.   // return ourselves to the trampoline.
    16.   if (T_CONT === this._inline) {
    17.     return true;
    18.   }
    19.   // onNextObject() hasn't fired yet. tell onNextObject
    20.   // that its ok to call _next b/c we are not within
    21.   // the trampoline anymore.
    22.   this._inline = T_IDLE;
    23. };

    QueryStream#_init()

    Initializes the query.

    show code

    1. QueryStream.prototype._init = function() {
    2.   if (this._destroyed) {
    3.     return;
    4.   }
    6.   var query = this.query,
    7.       model = query.model,
    8.       options = query._optionsForExec(model),
    9.       _this = this;
    11.   try {
    12.     query.cast(model);
    13.   } catch (err) {
    14.     return _this.destroy(err);
    15.   }
    17.   _this._fields = utils.clone(query._fields);
    18.   options.fields = query._castFields(_this._fields);
    20.   model.collection.find(query._conditions, options, function(err, cursor) {
    21.     if (err) {
    22.       return _this.destroy(err);
    23.     }
    24.     _this._cursor = cursor;
    25.     _this._next();
    26.   });
    27. };

    QueryStream#_next()

    Trampoline for pulling the next doc from cursor.

    See:

    show code

    1. QueryStream.prototype._next = function _next() {
    2.   if (this.paused || this._destroyed) {
    3.     this._running = false;
    4.     return this._running;
    5.   }
    7.   this._running = true;
    9.   if (this._buffer && this._buffer.length) {
    10.     var arg;
    11.     while (!this.paused && !this._destroyed && (arg = this._buffer.shift())) { // eslint-disable-line no-cond-assign
    12.       this._onNextObject.apply(this, arg);
    13.     }
    14.   }
    16.   // avoid stack overflows with large result sets.
    17.   // trampoline instead of recursion.
    18.   while (this.__next()) {
    19.   }
    20. };

    QueryStream#_onNextObject(err, doc)

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

    Parameters:

    show code

    1. QueryStream.prototype._onNextObject = function _onNextObject(err, doc) {
    2.   if (this._destroyed) {
    3.     return;
    4.   }
    6.   if (this.paused) {
    7.     this._buffer || (this._buffer = []);
    8.     this._buffer.push([err, doc]);
    9.     this._running = false;
    10.     return this._running;
    11.   }
    13.   if (err) {
    14.     return this.destroy(err);
    15.   }
    17.   // when doc is null we hit the end of the cursor
    18.   if (!doc) {
    19.     this.emit('end');
    20.     return this.destroy();
    21.   }
    23.   var opts = this.query._mongooseOptions;
    25.   if (!opts.populate) {
    26.     return opts.lean === true ?
    27.         emit(this, doc) :
    28.         createAndEmit(this, null, doc);
    29.   }
    31.   var _this = this;
    32.   var pop = helpers.preparePopulationOptionsMQ(_this.query, _this.query._mongooseOptions);
    34.   // Hack to work around gh-3108
    35.   pop.forEach(function(option) {
    36.     delete option.model;
    37.   });
    39.   pop.__noPromise = true;
    40.   _this.query.model.populate(doc, pop, function(err, doc) {
    41.     if (err) {
    42.       return _this.destroy(err);
    43.     }
    44.     return opts.lean === true ?
    45.         emit(_this, doc) :
    46.         createAndEmit(_this, pop, doc);
    47.   });
    48. };
    50. function createAndEmit(self, populatedIds, doc) {
    51.   var instance = helpers.createModel(self.query.model, doc, self._fields);
    52.   var opts = populatedIds ?
    53.     {populated: populatedIds} :
    54.     undefined;
    56.   instance.init(doc, opts, function(err) {
    57.     if (err) {
    58.       return self.destroy(err);
    59.     }
    60.     emit(self, instance);
    61.   });
    62. }

    QueryStream#destroy([err])

    Destroys the stream, closing the underlying cursor, which emits the close event. No more events will be emitted after the close event.

    Parameters:

    show code

    1. QueryStream.prototype.destroy = function(err) {
    2.   if (this._destroyed) {
    3.     return;
    4.   }
    5.   this._destroyed = true;
    6.   this._running = false;
    7.   this.readable = false;
    9.   if (this._cursor) {
    10.     this._cursor.close();
    11.   }
    13.   if (err) {
    14.     this.emit('error', err);
    15.   }
    17.   this.emit('close');
    18. };

    QueryStream#pause()

    Pauses this stream.

    show code

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

    QueryStream#pipe()

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

    See:

    Example:

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

    QueryStream(query, [options])

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

    Parameters:

    Inherits:

    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.

    1. var stream = Model.find().stream();
    3. stream.on('data', function (doc) {
    4.   // do something with the mongoose document
    5. }).on('error', function (err) {
    6.   // handle the error
    7. }).on('close', function () {
    8.   // the stream is closed
    9. });

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

    1. 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

    1. // JSON.stringify all documents before emitting
    2. var stream = Thing.find().stream({ transform: JSON.stringify });
    3. 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

    1. function QueryStream(query, options) {
    2.   Stream.call(this);
    4.   this.query = query;
    5.   this.readable = true;
    6.   this.paused = false;
    7.   this._cursor = null;
    8.   this._destroyed = null;
    9.   this._fields = null;
    10.   this._buffer = null;
    11.   this._inline = T_INIT;
    12.   this._running = false;
    13.   this._transform = options && typeof options.transform === 'function'
    14.       ? options.transform
    15.       : K;
    17.   // give time to hook up events
    18.   var _this = this;
    19.   process.nextTick(function() {
    20.     _this._init();
    21.   });
    22. }

    QueryStream#resume()

    Resumes this stream.

    show code

    1. QueryStream.prototype.resume = function() {
    2.   this.paused = false;
    4.   if (!this._cursor) {
    5.     // cannot start if not initialized
    6.     return;
    7.   }
    9.   // are we within the trampoline?
    10.   if (T_INIT === this._inline) {
    11.     return;
    12.   }
    14.   if (!this._running) {
    15.     // outside QueryStream control, need manual restart
    16.     return this._next();
    17.   }
    18. };

    QueryStream#paused

    Flag stating whether or not this stream is paused.

    show code

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

    QueryStream#readable

    Flag stating whether or not this stream is readable.

    show code

    1. QueryStream.prototype.readable;

  • model.js

    Model#$__delta()

    Produces a special query document of the modified properties used in updates.

    Model#$__version()

    Appends versioning to the where and update clauses.

    Model#$__where()

    Returns a query object

    Model#$where(argument)

    Creates a Query and specifies a $where condition.

    Parameters:

    • argument <String, Function> is a javascript string or anonymous function

    Returns:

    See:

    Sometimes you need to query for things in mongodb using a JavaScript expression. You can do so via find({ $where: javascript }), or you can use the mongoose shortcut method $where via a Query chain or from your mongoose Model.

    1. Blog.$where('this.username.indexOf("val") !== -1').exec(function (err, docs) {});

    Model#increment()

    Signal that we desire an increment of this documents version.

    See:

    Example:

    1. Model.findById(id, function (err, doc) {
    2.   doc.increment();
    3.   doc.save(function (err) { .. })
    4. })

    show code

    1. Model.prototype.increment = function increment() {
    2.   this.$__.version = VERSION_ALL;
    3.   return this;
    4. };

    Model#model(name)

    Returns another Model instance.

    Parameters:

    Example:

    1. var doc = new Tank;
    2. doc.model('User').findById(id, callback);

    show code

    1. Model.prototype.model = function model(name) {
    2.   return this.db.model(name);
    3. };

    Model(doc)

    Model constructor

    Parameters:

    • doc <Object> values with which to create the document

    Inherits:

    Events:

    • error: If listening to this event, ‘error’ is emitted when a document was saved without passing a callback and an error occurred. If not listening, the event bubbles to the connection used to create this Model.

    • index: Emitted after Model#ensureIndexes completes. If an error occurred it is passed with the event.

    • index-single-start: Emitted when an individual index starts within Model#ensureIndexes. The fields and options being used to build the index are also passed with the event.

    • index-single-done: Emitted when an individual index finishes within Model#ensureIndexes. If an error occurred it is passed with the event. The fields, options, and index name are also passed.

    Provides the interface to MongoDB collections as well as creates document instances.

    show code

    1. function Model(doc, fields, skipId) {
    2.   if (fields instanceof Schema) {
    3.     throw new TypeError('2nd argument to `Model` must be a POJO or string, ' +
    4.       '**not** a schema. Make sure you\'re calling `mongoose.model()`, not ' +
    5.       '`mongoose.Model()`.');
    6.   }
    7.   Document.call(this, doc, fields, skipId, true);
    8. }

    Model#remove([fn])

    Removes this document from the db.

    Parameters:

    Returns:

    Example:

    1. product.remove(function (err, product) {
    2.   if (err) return handleError(err);
    3.   Product.findById(product._id, function (err, product) {
    4.     console.log(product) // null
    5.   })
    6. })

    As an extra measure of flow control, remove will return a Promise (bound to fn if passed) so it could be chained, or hooked to recive errors

    Example:

    1. product.remove().then(function (product) {
    2.    ...
    3. }).catch(function (err) {
    4.    assert.ok(err)
    5. })

    show code

    1. Model.prototype.remove = function remove(options, fn) {
    2.   if (typeof options === 'function') {
    3.     fn = options;
    4.     options = undefined;
    5.   }
    7.   var _this = this;
    9.   if (!options) {
    10.     options = {};
    11.   }
    13.   if (this.$__.removing) {
    14.     if (fn) {
    15.       this.$__.removing.then(
    16.           function(res) { fn(null, res); },
    17.           function(err) { fn(err); });
    18.     }
    19.     return this;
    20.   }
    21.   if (this.$__.isDeleted) {
    22.     setImmediate(function() {
    23.       fn(null, _this);
    24.     });
    25.     return this;
    26.   }
    28.   var Promise = PromiseProvider.get();
    30.   if (fn) {
    31.     fn = this.constructor.$wrapCallback(fn);
    32.   }
    34.   this.$__.removing = new Promise.ES6(function(resolve, reject) {
    35.     var where = _this.$__where();
    36.     if (where instanceof Error) {
    37.       reject(where);
    38.       fn && fn(where);
    39.       return;
    40.     }
    42.     if (!options.safe && _this.schema.options.safe) {
    43.       options.safe = _this.schema.options.safe;
    44.     }
    46.     _this.collection.remove(where, options, function(err) {
    47.       if (!err) {
    48.         _this.$__.isDeleted = true;
    49.         _this.emit('remove', _this);
    50.         _this.constructor.emit('remove', _this);
    51.         resolve(_this);
    52.         fn && fn(null, _this);
    53.         return;
    54.       }
    55.       _this.$__.isDeleted = false;
    56.       reject(err);
    57.       fn && fn(err);
    58.     });
    59.   });
    60.   return this.$__.removing;
    61. };

    Model#save([options], [options.safe], [options.validateBeforeSave], [fn])

    Saves this document.

    Parameters:

    Returns:

    See:

    Example:

    1. product.sold = Date.now();
    2. product.save(function (err, product, numAffected) {
    3.   if (err) ..
    4. })

    The callback will receive three parameters

    1. err if an error occurred
    2. product which is the saved product
    3. numAffected will be 1 when the document was successfully persisted to MongoDB, otherwise 0. Unless you tweak mongoose’s internals, you don’t need to worry about checking this parameter for errors - checking err is sufficient to make sure your document was properly saved.

    As an extra measure of flow control, save will return a Promise.

    Example:

    1. product.save().then(function(product) {
    2.    ...
    3. });

    For legacy reasons, mongoose stores object keys in reverse order on initial
    save. That is, { a: 1, b: 2 } will be saved as { b: 2, a: 1 } in
    MongoDB. To override this behavior, set
    the toObject.retainKeyOrder option
    to true on your schema.

    show code

    1. Model.prototype.save = function(options, fn) {
    2.   if (typeof options === 'function') {
    3.     fn = options;
    4.     options = undefined;
    5.   }
    7.   if (!options) {
    8.     options = {};
    9.   }
    11.   if (fn) {
    12.     fn = this.constructor.$wrapCallback(fn);
    13.   }
    15.   return this.$__save(options, fn);
    16. };

    Model.aggregate([...], [callback])

    Performs aggregations on the models collection.

    show code

    1. Model.aggregate = function aggregate() {
    2.   var args = [].slice.call(arguments),
    3.       aggregate,
    4.       callback;
    6.   if (typeof args[args.length - 1] === 'function') {
    7.     callback = args.pop();
    8.   }
    10.   if (args.length === 1 && util.isArray(args[0])) {
    11.     aggregate = new Aggregate(args[0]);
    12.   } else {
    13.     aggregate = new Aggregate(args);
    14.   }
    16.   aggregate.model(this);
    18.   if (typeof callback === 'undefined') {
    19.     return aggregate;
    20.   }
    22.   if (callback) {
    23.     callback = this.$wrapCallback(callback);
    24.   }
    26.   aggregate.exec(callback);
    27. };

    Parameters:

    Returns:

    See:

    If a callback is passed, the aggregate is executed and a Promise is returned. If a callback is not passed, the aggregate itself is returned.

    This function does not trigger any middleware.

    Example:

    1. // Find the max balance of all accounts
    2. Users.aggregate(
    3.   { $group: { _id: null, maxBalance: { $max: '$balance' }}},
    4.   { $project: { _id: 0, maxBalance: 1 }},
    5.   function (err, res) {
    6.     if (err) return handleError(err);
    7.     console.log(res); // [ { maxBalance: 98000 } ]
    8.   });
    10. // Or use the aggregation pipeline builder.
    11. Users.aggregate()
    12.   .group({ _id: null, maxBalance: { $max: '$balance' } })
    13.   .select('-id maxBalance')
    14.   .exec(function (err, res) {
    15.     if (err) return handleError(err);
    16.     console.log(res); // [ { maxBalance: 98 } ]
    17. });

    NOTE:

    • Arguments are not cast to the model’s schema because $project operators allow redefining the “shape” of the documents at any stage of the pipeline, which may leave documents in an incompatible format.
    • The documents returned are plain javascript objects, not mongoose documents (since any shape of document can be returned).
    • Requires MongoDB >= 2.1

    Model.bulkWrite(ops, [options], [callback])

    Sends multiple insertOne, updateOne, updateMany, replaceOne,
    deleteOne, and/or deleteMany operations to the MongoDB server in one
    command. This is faster than sending multiple independent operations (like)
    if you use create()) because with bulkWrite() there is only one round
    trip to MongoDB.

    show code

    1. Model.bulkWrite = function(ops, options, callback) {
    2.   var Promise = PromiseProvider.get();
    3.   var _this = this;
    4.   if (typeof options === 'function') {
    5.     callback = options;
    6.     options = null;
    7.   }
    8.   if (callback) {
    9.     callback = this.$wrapCallback(callback);
    10.   }
    11.   options = options || {};
    13.   var validations = ops.map(function(op) {
    14.     if (op['insertOne']) {
    15.       return function(callback) {
    16.         op['insertOne']['document'] = new _this(op['insertOne']['document']);
    17.         op['insertOne']['document'].validate({ __noPromise: true }, function(error) {
    18.           if (error) {
    19.             return callback(error);
    20.           }
    21.           callback(null);
    22.         });
    23.       };
    24.     } else if (op['updateOne']) {
    25.       op = op['updateOne'];
    26.       return function(callback) {
    27.         try {
    28.           op['filter'] = cast(_this.schema, op['filter']);
    29.           op['update'] = castUpdate(_this.schema, op['update'],
    30.             _this.schema.options.strict);
    31.           if (op.setDefaultsOnInsert) {
    32.             setDefaultsOnInsert(op['filter'], _this.schema, op['update'], {
    33.               setDefaultsOnInsert: true,
    34.               upsert: op.upsert
    35.             });
    36.           }
    37.         } catch (error) {
    38.           return callback(error);
    39.         }
    41.         callback(null);
    42.       };
    43.     } else if (op['updateMany']) {
    44.       op = op['updateMany'];
    45.       return function(callback) {
    46.         try {
    47.           op['filter'] = cast(_this.schema, op['filter']);
    48.           op['update'] = castUpdate(_this.schema, op['update'], {
    49.             strict: _this.schema.options.strict,
    50.             overwrite: false
    51.           });
    52.           if (op.setDefaultsOnInsert) {
    53.             setDefaultsOnInsert(op['filter'], _this.schema, op['update'], {
    54.               setDefaultsOnInsert: true,
    55.               upsert: op.upsert
    56.             });
    57.           }
    58.         } catch (error) {
    59.           return callback(error);
    60.         }
    62.         callback(null);
    63.       };
    64.     } else if (op['replaceOne']) {
    65.       return function(callback) {
    66.         try {
    67.           op['replaceOne']['filter'] = cast(_this.schema,
    68.             op['replaceOne']['filter']);
    69.         } catch (error) {
    70.           return callback(error);
    71.         }
    73.         // set `skipId`, otherwise we get "_id field cannot be changed"
    74.         op['replaceOne']['replacement'] =
    75.           new _this(op['replaceOne']['replacement'], null, true);
    76.         op['replaceOne']['replacement'].validate({ __noPromise: true }, function(error) {
    77.           if (error) {
    78.             return callback(error);
    79.           }
    80.           callback(null);
    81.         });
    82.       };
    83.     } else if (op['deleteOne']) {
    84.       return function(callback) {
    85.         try {
    86.           op['deleteOne']['filter'] = cast(_this.schema,
    87.             op['deleteOne']['filter']);
    88.         } catch (error) {
    89.           return callback(error);
    90.         }
    92.         callback(null);
    93.       };
    94.     } else if (op['deleteMany']) {
    95.       return function(callback) {
    96.         try {
    97.           op['deleteMany']['filter'] = cast(_this.schema,
    98.             op['deleteMany']['filter']);
    99.         } catch (error) {
    100.           return callback(error);
    101.         }
    103.         callback(null);
    104.       };
    105.     } else {
    106.       return function(callback) {
    107.         callback(new Error('Invalid op passed to `bulkWrite()`'));
    108.       };
    109.     }
    110.   });
    112.   var promise = new Promise.ES6(function(resolve, reject) {
    113.     parallel(validations, function(error) {
    114.       if (error) {
    115.         callback && callback(error);
    116.         return reject(error);
    117.       }
    119.       _this.collection.bulkWrite(ops, options, function(error, res) {
    120.         if (error) {
    121.           callback && callback(error);
    122.           return reject(error);
    123.         }
    125.         callback && callback(null, res);
    126.         resolve(res);
    127.       });
    128.     });
    129.   });
    131.   return promise;
    132. };

    Parameters:

    • ops <Array>
    • [options] <Object>
    • [callback] <Function> callback <code>function(error, bulkWriteOpResult) {}</code>

    Returns:

    • <Promise> resolves to a `BulkWriteOpResult` if the operation succeeds

    See:

    Mongoose will perform casting on all operations you provide.

    This function does not trigger any middleware, not save() nor update().
    If you need to trigger
    save() middleware for every document use create() instead.

    Example:

    1. Character.bulkWrite([
    2.   {
    3.     insertOne: {
    4.       document: {
    5.         name: 'Eddard Stark',
    6.         title: 'Warden of the North'
    7.       }
    8.     }
    9.   },
    10.   {
    11.     updateOne: {
    12.       filter: { name: 'Eddard Stark' },
    13.       // If you were using the MongoDB driver directly, you'd need to do
    14.       // `update: { $set: { title: ... } }` but mongoose adds $set for
    15.       // you.
    16.       update: { title: 'Hand of the King' }
    17.     }
    18.   },
    19.   {
    20.     deleteOne: {
    21.       {
    22.         filter: { name: 'Eddard Stark' }
    23.       }
    24.     }
    25.   }
    26. ]).then(handleResult);

    Model.count(conditions, [callback])

    Counts number of matching documents in a database collection.

    show code

    1. Model.count = function count(conditions, callback) {
    2.   if (typeof conditions === 'function') {
    3.     callback = conditions;
    4.     conditions = {};
    5.   }
    7.   // get the mongodb collection object
    8.   var mq = new this.Query({}, {}, this, this.collection);
    10.   if (callback) {
    11.     callback = this.$wrapCallback(callback);
    12.   }
    14.   return mq.count(conditions, callback);
    15. };

    Parameters:

    Returns:

    Example:

    1. Adventure.count({ type: 'jungle' }, function (err, count) {
    2.   if (err) ..
    3.   console.log('there are %d jungle adventures', count);
    4. });

    Model.create(doc(s), [callback])

    Shortcut for saving one or more documents to the database.
    MyModel.create(docs) does new MyModel(doc).save() for every doc in
    docs.

    show code

    1. Model.create = function create(doc, callback) {
    2.   var args;
    3.   var cb;
    4.   var discriminatorKey = this.schema.options.discriminatorKey;
    6.   if (Array.isArray(doc)) {
    7.     args = doc;
    8.     cb = callback;
    9.   } else {
    10.     var last = arguments[arguments.length - 1];
    11.     // Handle falsy callbacks re: #5061
    12.     if (typeof last === 'function' || !last) {
    13.       cb = last;
    14.       args = utils.args(arguments, 0, arguments.length - 1);
    15.     } else {
    16.       args = utils.args(arguments);
    17.     }
    18.   }
    20.   var Promise = PromiseProvider.get();
    21.   var _this = this;
    22.   if (cb) {
    23.     cb = this.$wrapCallback(cb);
    24.   }
    26.   var promise = new Promise.ES6(function(resolve, reject) {
    27.     if (args.length === 0) {
    28.       setImmediate(function() {
    29.         cb && cb(null);
    30.         resolve(null);
    31.       });
    32.       return;
    33.     }
    35.     var toExecute = [];
    36.     var firstError;
    37.     args.forEach(function(doc) {
    38.       toExecute.push(function(callback) {
    39.         var Model = _this.discriminators && doc[discriminatorKey] ?
    40.           _this.discriminators[doc[discriminatorKey]] :
    41.           _this;
    42.         var toSave = doc;
    43.         var callbackWrapper = function(error, doc) {
    44.           if (error) {
    45.             if (!firstError) {
    46.               firstError = error;
    47.             }
    48.             return callback(null, { error: error });
    49.           }
    50.           callback(null, { doc: doc });
    51.         };
    53.         if (!(toSave instanceof Model)) {
    54.           try {
    55.             toSave = new Model(toSave);
    56.           } catch (error) {
    57.             return callbackWrapper(error);
    58.           }
    59.         }
    61.         // Hack to avoid getting a promise because of
    62.         // $__registerHooksFromSchema
    63.         if (toSave.$__original_save) {
    64.           toSave.$__original_save({ __noPromise: true }, callbackWrapper);
    65.         } else {
    66.           toSave.save({ __noPromise: true }, callbackWrapper);
    67.         }
    68.       });
    69.     });
    71.     parallel(toExecute, function(error, res) {
    72.       var savedDocs = [];
    73.       var len = res.length;
    74.       for (var i = 0; i < len; ++i) {
    75.         if (res[i].doc) {
    76.           savedDocs.push(res[i].doc);
    77.         }
    78.       }
    80.       if (firstError) {
    81.         if (cb) {
    82.           cb(firstError, savedDocs);
    83.         } else {
    84.           reject(firstError);
    85.         }
    86.         return;
    87.       }
    89.       if (doc instanceof Array) {
    90.         resolve(savedDocs);
    91.         cb && cb.call(_this, null, savedDocs);
    92.       } else {
    93.         resolve.apply(promise, savedDocs);
    94.         if (cb) {
    95.           cb.apply(_this, [null].concat(savedDocs));
    96.         }
    97.       }
    98.     });
    99.   });
    101.   return promise;
    102. };

    Parameters:

    Returns:

    This function triggers the following middleware

    • save()

    Example:

    1. // pass individual docs
    2. Candy.create({ type: 'jelly bean' }, { type: 'snickers' }, function (err, jellybean, snickers) {
    3.   if (err) // ...
    4. });
    6. // pass an array
    7. var array = [{ type: 'jelly bean' }, { type: 'snickers' }];
    8. Candy.create(array, function (err, candies) {
    9.   if (err) // ...
    11.   var jellybean = candies[0];
    12.   var snickers = candies[1];
    13.   // ...
    14. });
    16. // callback is optional; use the returned promise if you like:
    17. var promise = Candy.create({ type: 'jawbreaker' });
    18. promise.then(function (jawbreaker) {
    19.   // ...
    20. })

    Model.createIndexes([options], [cb])

    Similar to ensureIndexes(), except for it uses the createIndex
    function. The ensureIndex() function checks to see if an index with that
    name already exists, and, if not, does not attempt to create the index.
    createIndex() bypasses this check.

    show code

    1. Model.createIndexes = function createIndexes(options, callback) {
    2.   if (typeof options === 'function') {
    3.     callback = options;
    4.     options = {};
    5.   }
    6.   options = options || {};
    7.   options.createIndex = true;
    8.   return this.ensureIndexes(options, callback);
    9. };
    11. function _ensureIndexes(model, options, callback) {
    12.   var indexes = model.schema.indexes();
    13.   options = options || {};
    15.   var done = function(err) {
    16.     if (err && model.schema.options.emitIndexErrors) {
    17.       model.emit('error', err);
    18.     }
    19.     model.emit('index', err);
    20.     callback && callback(err);
    21.   };
    23.   if (!indexes.length) {
    24.     setImmediate(function() {
    25.       done();
    26.     });
    27.     return;
    28.   }
    29.   // Indexes are created one-by-one to support how MongoDB < 2.4 deals
    30.   // with background indexes.
    32.   var indexSingleDone = function(err, fields, options, name) {
    33.     model.emit('index-single-done', err, fields, options, name);
    34.   };
    35.   var indexSingleStart = function(fields, options) {
    36.     model.emit('index-single-start', fields, options);
    37.   };
    39.   var create = function() {
    40.     if (options._automatic) {
    41.       if (model.schema.options.autoIndex === false ||
    42.           (model.schema.options.autoIndex == null && model.db.config.autoIndex === false)) {
    43.         return done();
    44.       }
    45.     }
    47.     var index = indexes.shift();
    48.     if (!index) return done();
    50.     var indexFields = index[0];
    51.     var indexOptions = index[1];
    52.     _handleSafe(options);
    54.     indexSingleStart(indexFields, options);
    55.     var methodName = options.createIndex ? 'createIndex' : 'ensureIndex';
    56.     model.collection[methodName](indexFields, indexOptions, utils.tick(function(err, name) {
    57.       indexSingleDone(err, indexFields, indexOptions, name);
    58.       if (err) {
    59.         return done(err);
    60.       }
    61.       create();
    62.     }));
    63.   };
    65.   setImmediate(function() {
    66.     // If buffering is off, do this manually.
    67.     if (options._automatic && !model.collection.collection) {
    68.       model.collection.addQueue(create, []);
    69.     } else {
    70.       create();
    71.     }
    72.   });
    73. }
    75. function _handleSafe(options) {
    76.   if (options.safe) {
    77.     if (typeof options.safe === 'boolean') {
    78.       options.w = options.safe;
    79.       delete options.safe;
    80.     }
    81.     if (typeof options.safe === 'object') {
    82.       options.w = options.safe.w;
    83.       options.j = options.safe.j;
    84.       options.wtimeout = options.safe.wtimeout;
    85.       delete options.safe;
    86.     }
    87.   }
    88. }

    Parameters:

    Returns:

    Model.deleteMany(conditions, [callback])

    Deletes all of the documents that match conditions from the collection.
    Behaves like remove(), but deletes all documents that match conditions
    regardless of the single option.

    show code

    1. Model.deleteMany = function deleteMany(conditions, callback) {
    2.   if (typeof conditions === 'function') {
    3.     callback = conditions;
    4.     conditions = {};
    5.   }
    7.   // get the mongodb collection object
    8.   var mq = new this.Query(conditions, {}, this, this.collection);
    10.   if (callback) {
    11.     callback = this.$wrapCallback(callback);
    12.   }
    14.   return mq.deleteMany(callback);
    15. };

    Parameters:

    Returns:

    Example:

    1. Character.deleteMany({ name: /Stark/, age: { $gte: 18 } }, function (err) {});

    Note:

    Like Model.remove(), this function does not trigger pre('remove') or post('remove') hooks.

    Model.deleteOne(conditions, [callback])

    Deletes the first document that matches conditions from the collection.
    Behaves like remove(), but deletes at most one document regardless of the
    single option.

    show code

    1. Model.deleteOne = function deleteOne(conditions, callback) {
    2.   if (typeof conditions === 'function') {
    3.     callback = conditions;
    4.     conditions = {};
    5.   }
    7.   // get the mongodb collection object
    8.   var mq = new this.Query(conditions, {}, this, this.collection);
    10.   if (callback) {
    11.     callback = this.$wrapCallback(callback);
    12.   }
    14.   return mq.deleteOne(callback);
    15. };

    Parameters:

    Returns:

    Example:

    1. Character.deleteOne({ name: 'Eddard Stark' }, function (err) {});

    Note:

    Like Model.remove(), this function does not trigger pre('remove') or post('remove') hooks.

    Model.discriminator(name, schema)

    Adds a discriminator type.

    show code

    1. Model.discriminator = function(name, schema) {
    2.   var model;
    3.   if (typeof name === 'function') {
    4.     model = name;
    5.     name = utils.getFunctionName(model);
    6.     if (!(model.prototype instanceof Model)) {
    7.       throw new Error('The provided class ' + name + ' must extend Model');
    8.     }
    9.   }
    11.   schema = discriminator(this, name, schema);
    12.   if (this.db.models[name]) {
    13.     throw new OverwriteModelError(name);
    14.   }
    16.   schema.$isRootDiscriminator = true;
    18.   model = this.db.model(model || name, schema, this.collection.name);
    19.   this.discriminators[name] = model;
    20.   var d = this.discriminators[name];
    21.   d.prototype.__proto__ = this.prototype;
    22.   Object.defineProperty(d, 'baseModelName', {
    23.     value: this.modelName,
    24.     configurable: true,
    25.     writable: false
    26.   });
    28.   // apply methods and statics
    29.   applyMethods(d, schema);
    30.   applyStatics(d, schema);
    32.   return d;
    33. };
    35. // Model (class) features

    Parameters:

    • name <String> discriminator model name
    • schema <Schema> discriminator model schema

    Example:

    1. function BaseSchema() {
    2.   Schema.apply(this, arguments);
    4.   this.add({
    5.     name: String,
    6.     createdAt: Date
    7.   });
    8. }
    9. util.inherits(BaseSchema, Schema);
    11. var PersonSchema = new BaseSchema();
    12. var BossSchema = new BaseSchema({ department: String });
    14. var Person = mongoose.model('Person', PersonSchema);
    15. var Boss = Person.discriminator('Boss', BossSchema);

    Model.distinct(field, [conditions], [callback])

    Creates a Query for a distinct operation.

    show code

    1. Model.distinct = function distinct(field, conditions, callback) {
    2.   // get the mongodb collection object
    3.   var mq = new this.Query({}, {}, this, this.collection);
    5.   if (typeof conditions === 'function') {
    6.     callback = conditions;
    7.     conditions = {};
    8.   }
    9.   if (callback) {
    10.     callback = this.$wrapCallback(callback);
    11.   }
    13.   return mq.distinct(field, conditions, callback);
    14. };

    Parameters:

    Returns:

    Passing a callback immediately executes the query.

    Example

    1. Link.distinct('url', { clicks: {$gt: 100}}, function (err, result) {
    2.   if (err) return handleError(err);
    4.   assert(Array.isArray(result));
    5.   console.log('unique urls with more than 100 clicks', result);
    6. })
    8. var query = Link.distinct('url');
    9. query.exec(callback);

    Model.ensureIndexes([options], [cb])

    Sends createIndex commands to mongo for each index declared in the schema.
    The createIndex commands are sent in series.

    show code

    1. Model.ensureIndexes = function ensureIndexes(options, callback) {
    2.   if (typeof options === 'function') {
    3.     callback = options;
    4.     options = null;
    5.   }
    7.   if (options && options.__noPromise) {
    8.     _ensureIndexes(this, options, callback);
    9.     return;
    10.   }
    12.   if (callback) {
    13.     callback = this.$wrapCallback(callback);
    14.   }
    16.   var _this = this;
    17.   var Promise = PromiseProvider.get();
    18.   return new Promise.ES6(function(resolve, reject) {
    19.     _ensureIndexes(_this, options || {}, function(error) {
    20.       if (error) {
    21.         callback && callback(error);
    22.         reject(error);
    23.       }
    24.       callback && callback();
    25.       resolve();
    26.     });
    27.   });
    28. };

    Parameters:

    Returns:

    Example:

    1. Event.ensureIndexes(function (err) {
    2.   if (err) return handleError(err);
    3. });

    After completion, an index event is emitted on this Model passing an error if one occurred.

    Example:

    1. var eventSchema = new Schema({ thing: { type: 'string', unique: true }})
    2. var Event = mongoose.model('Event', eventSchema);
    4. Event.on('index', function (err) {
    5.   if (err) console.error(err); // error occurred during index creation
    6. })

    NOTE: It is not recommended that you run this in production. Index creation may impact database performance depending on your load. Use with caution.

    Model.find(conditions, [projection], [options], [callback])

    Finds documents

    show code

    1. Model.find = function find(conditions, projection, options, callback) {
    2.   if (typeof conditions === 'function') {
    3.     callback = conditions;
    4.     conditions = {};
    5.     projection = null;
    6.     options = null;
    7.   } else if (typeof projection === 'function') {
    8.     callback = projection;
    9.     projection = null;
    10.     options = null;
    11.   } else if (typeof options === 'function') {
    12.     callback = options;
    13.     options = null;
    14.   }
    16.   var mq = new this.Query({}, {}, this, this.collection);
    17.   mq.select(projection);
    18.   mq.setOptions(options);
    19.   if (this.schema.discriminatorMapping &&
    20.       this.schema.discriminatorMapping.isRoot &&
    21.       mq.selectedInclusively()) {
    22.     // Need to select discriminator key because original schema doesn't have it
    23.     mq.select(this.schema.options.discriminatorKey);
    24.   }
    26.   if (callback) {
    27.     callback = this.$wrapCallback(callback);
    28.   }
    30.   return mq.find(conditions, callback);
    31. };

    Parameters:

    Returns:

    See:

    The conditions are cast to their respective SchemaTypes before the command is sent.

    Examples:

    1. // named john and at least 18
    2. MyModel.find({ name: 'john', age: { $gte: 18 }});
    4. // executes immediately, passing results to callback
    5. MyModel.find({ name: 'john', age: { $gte: 18 }}, function (err, docs) {});
    7. // name LIKE john and only selecting the "name" and "friends" fields, executing immediately
    8. MyModel.find({ name: /john/i }, 'name friends', function (err, docs) { })
    10. // passing options
    11. MyModel.find({ name: /john/i }, null, { skip: 10 })
    13. // passing options and executing immediately
    14. MyModel.find({ name: /john/i }, null, { skip: 10 }, function (err, docs) {});
    16. // executing a query explicitly
    17. var query = MyModel.find({ name: /john/i }, null, { skip: 10 })
    18. query.exec(function (err, docs) {});
    20. // using the promise returned from executing a query
    21. var query = MyModel.find({ name: /john/i }, null, { skip: 10 });
    22. var promise = query.exec();
    23. promise.addBack(function (err, docs) {});

    Model.findById(id, [projection], [options], [callback])

    Finds a single document by its _id field. findById(id) is almost*
    equivalent to findOne({ _id: id }). If you want to query by a document’s
    _id, use findById() instead of findOne().

    show code

    1. Model.findById = function findById(id, projection, options, callback) {
    2.   if (typeof id === 'undefined') {
    3.     id = null;
    4.   }
    6.   if (callback) {
    7.     callback = this.$wrapCallback(callback);
    8.   }
    10.   return this.findOne({_id: id}, projection, options, callback);
    11. };

    Parameters:

    Returns:

    See:

    The id is cast based on the Schema before sending the command.

    This function triggers the following middleware

    • findOne()

    * Except for how it treats undefined. If you use findOne(), you’ll see
    that findOne(undefined) and findOne({ _id: undefined }) are equivalent
    to findOne({}) and return arbitrary documents. However, mongoose
    translates findById(undefined) into findOne({ _id: null }).

    Example:

    1. // find adventure by id and execute immediately
    2. Adventure.findById(id, function (err, adventure) {});
    4. // same as above
    5. Adventure.findById(id).exec(callback);
    7. // select only the adventures name and length
    8. Adventure.findById(id, 'name length', function (err, adventure) {});
    10. // same as above
    11. Adventure.findById(id, 'name length').exec(callback);
    13. // include all properties except for `length`
    14. Adventure.findById(id, '-length').exec(function (err, adventure) {});
    16. // passing options (in this case return the raw js objects, not mongoose documents by passing `lean`
    17. Adventure.findById(id, 'name', { lean: true }, function (err, doc) {});
    19. // same as above
    20. Adventure.findById(id, 'name').lean().exec(function (err, doc) {});

    Model.findByIdAndRemove(id, [options], [callback])

    Issue a mongodb findAndModify remove command by a document’s _id field. findByIdAndRemove(id, ...) is equivalent to findOneAndRemove({ _id: id }, ...).

    show code

    1. Model.findByIdAndRemove = function(id, options, callback) {
    2.   if (arguments.length === 1 && typeof id === 'function') {
    3.     var msg = 'Model.findByIdAndRemove(): First argument must not be a function.
    5. '
    6.         + '  ' + this.modelName + '.findByIdAndRemove(id, callback)
    7. '
    8.         + '  ' + this.modelName + '.findByIdAndRemove(id)
    9. '
    10.         + '  ' + this.modelName + '.findByIdAndRemove()
    11. ';
    12.     throw new TypeError(msg);
    13.   }
    14.   if (callback) {
    15.     callback = this.$wrapCallback(callback);
    16.   }
    18.   return this.findOneAndRemove({_id: id}, options, callback);
    19. };

    Parameters:

    Returns:

    See:

    Finds a matching document, removes it, passing the found document (if any) to the callback.

    Executes immediately if callback is passed, else a Query object is returned.

    This function triggers the following middleware

    • findOneAndRemove()

    Options:

    Examples:

    1. A.findByIdAndRemove(id, options, callback) // executes
    2. A.findByIdAndRemove(id, options)  // return Query
    3. A.findByIdAndRemove(id, callback) // executes
    4. A.findByIdAndRemove(id) // returns Query
    5. A.findByIdAndRemove()           // returns Query

    Model.findByIdAndUpdate(id, [update], [options], [options.lean], [callback])

    Issues a mongodb findAndModify update command by a document’s _id field.
    findByIdAndUpdate(id, ...) is equivalent to findOneAndUpdate({ _id: id }, ...).

    show code

    1. Model.findByIdAndUpdate = function(id, update, options, callback) {
    2.   if (callback) {
    3.     callback = this.$wrapCallback(callback);
    4.   }
    5.   if (arguments.length === 1) {
    6.     if (typeof id === 'function') {
    7.       var msg = 'Model.findByIdAndUpdate(): First argument must not be a function.
    9. '
    10.           + '  ' + this.modelName + '.findByIdAndUpdate(id, callback)
    11. '
    12.           + '  ' + this.modelName + '.findByIdAndUpdate(id)
    13. '
    14.           + '  ' + this.modelName + '.findByIdAndUpdate()
    15. ';
    16.       throw new TypeError(msg);
    17.     }
    18.     return this.findOneAndUpdate({_id: id}, undefined);
    19.   }
    21.   // if a model is passed in instead of an id
    22.   if (id instanceof Document) {
    23.     id = id._id;
    24.   }
    26.   return this.findOneAndUpdate.call(this, {_id: id}, update, options, callback);
    27. };

    Parameters:

    Returns:

    See:

    Finds a matching document, updates it according to the update arg,
    passing any options, and returns the found document (if any) to the
    callback. The query executes immediately if callback is passed else a
    Query object is returned.

    This function triggers the following middleware

    • findOneAndUpdate()

    Options:

    • new: bool - true to return the modified document rather than the original. defaults to false
    • upsert: bool - creates the object if it doesn’t exist. defaults to false.
    • runValidators: if true, runs update validators on this command. Update validators validate the update operation against the model’s schema.
    • setDefaultsOnInsert: if this and upsert are true, mongoose will apply the defaults specified in the model’s schema if a new document is created. This option only works on MongoDB >= 2.4 because it relies on MongoDB’s $setOnInsert operator.
    • sort: if multiple docs are found by the conditions, sets the sort order to choose which doc to update
    • select: sets the document fields to return
    • passRawResult: if true, passes the raw result from the MongoDB driver as the third callback parameter
    • strict: overwrites the schema’s strict mode option for this update
    • runSettersOnQuery: bool - if true, run all setters defined on the associated model’s schema for all fields defined in the query and the update.

    Examples:

    1. A.findByIdAndUpdate(id, update, options, callback) // executes
    2. A.findByIdAndUpdate(id, update, options)  // returns Query
    3. A.findByIdAndUpdate(id, update, callback) // executes
    4. A.findByIdAndUpdate(id, update)           // returns Query
    5. A.findByIdAndUpdate()                     // returns Query

    Note:

    All top level update keys which are not atomic operation names are treated as set operations:

    Example:

    1. Model.findByIdAndUpdate(id, { name: 'jason bourne' }, options, callback)
    3. // is sent as
    4. Model.findByIdAndUpdate(id, { $set: { name: 'jason bourne' }}, options, callback)

    This helps prevent accidentally overwriting your document with { name: 'jason bourne' }.

    Note:

    Values are cast to their appropriate types when using the findAndModify helpers.
    However, the below are not executed by default.

    • defaults. Use the setDefaultsOnInsert option to override.
    • setters. Use the runSettersOnQuery option to override.

    findAndModify helpers support limited validation. You can
    enable these by setting the runValidators options,
    respectively.

    If you need full-fledged validation, use the traditional approach of first
    retrieving the document.

    1. Model.findById(id, function (err, doc) {
    2.   if (err) ..
    3.   doc.name = 'jason bourne';
    4.   doc.save(callback);
    5. });

    Model.findOne([conditions], [projection], [options], [callback])

    Finds one document.

    show code

    1. Model.findOne = function findOne(conditions, projection, options, callback) {
    2.   if (typeof options === 'function') {
    3.     callback = options;
    4.     options = null;
    5.   } else if (typeof projection === 'function') {
    6.     callback = projection;
    7.     projection = null;
    8.     options = null;
    9.   } else if (typeof conditions === 'function') {
    10.     callback = conditions;
    11.     conditions = {};
    12.     projection = null;
    13.     options = null;
    14.   }
    16.   // get the mongodb collection object
    17.   var mq = new this.Query({}, {}, this, this.collection);
    18.   mq.select(projection);
    19.   mq.setOptions(options);
    20.   if (this.schema.discriminatorMapping &&
    21.       this.schema.discriminatorMapping.isRoot &&
    22.       mq.selectedInclusively()) {
    23.     mq.select(this.schema.options.discriminatorKey);
    24.   }
    26.   if (callback) {
    27.     callback = this.$wrapCallback(callback);
    28.   }
    30.   return mq.findOne(conditions, callback);
    31. };

    Parameters:

    Returns:

    See:

    The conditions are cast to their respective SchemaTypes before the command is sent.

    Note: conditions is optional, and if conditions is null or undefined,
    mongoose will send an empty findOne command to MongoDB, which will return
    an arbitrary document. If you’re querying by _id, use findById() instead.

    Example:

    1. // find one iphone adventures - iphone adventures??
    2. Adventure.findOne({ type: 'iphone' }, function (err, adventure) {});
    4. // same as above
    5. Adventure.findOne({ type: 'iphone' }).exec(function (err, adventure) {});
    7. // select only the adventures name
    8. Adventure.findOne({ type: 'iphone' }, 'name', function (err, adventure) {});
    10. // same as above
    11. Adventure.findOne({ type: 'iphone' }, 'name').exec(function (err, adventure) {});
    13. // specify options, in this case lean
    14. Adventure.findOne({ type: 'iphone' }, 'name', { lean: true }, callback);
    16. // same as above
    17. Adventure.findOne({ type: 'iphone' }, 'name', { lean: true }).exec(callback);
    19. // chaining findOne queries (same as above)
    20. Adventure.findOne({ type: 'iphone' }).select('name').lean().exec(callback);

    Model.findOneAndRemove(conditions, [options], [callback])

    Issue a mongodb findAndModify remove command.

    show code

    1. Model.findOneAndRemove = function(conditions, options, callback) {
    2.   if (arguments.length === 1 && typeof conditions === 'function') {
    3.     var msg = 'Model.findOneAndRemove(): First argument must not be a function.
    5. '
    6.         + '  ' + this.modelName + '.findOneAndRemove(conditions, callback)
    7. '
    8.         + '  ' + this.modelName + '.findOneAndRemove(conditions)
    9. '
    10.         + '  ' + this.modelName + '.findOneAndRemove()
    11. ';
    12.     throw new TypeError(msg);
    13.   }
    15.   if (typeof options === 'function') {
    16.     callback = options;
    17.     options = undefined;
    18.   }
    19.   if (callback) {
    20.     callback = this.$wrapCallback(callback);
    21.   }
    23.   var fields;
    24.   if (options) {
    25.     fields = options.select;
    26.     options.select = undefined;
    27.   }
    29.   var mq = new this.Query({}, {}, this, this.collection);
    30.   mq.select(fields);
    32.   return mq.findOneAndRemove(conditions, options, callback);
    33. };

    Parameters:

    Returns:

    See:

    Finds a matching document, removes it, passing the found document (if any) to the callback.

    Executes immediately if callback is passed else a Query object is returned.

    This function triggers the following middleware

    • findOneAndRemove()

    Options:

    Examples:

    1. A.findOneAndRemove(conditions, options, callback) // executes
    2. A.findOneAndRemove(conditions, options)  // return Query
    3. A.findOneAndRemove(conditions, callback) // executes
    4. A.findOneAndRemove(conditions) // returns Query
    5. A.findOneAndRemove()           // returns Query

    Values are cast to their appropriate types when using the findAndModify helpers.
    However, the below are not executed by default.

    • defaults. Use the setDefaultsOnInsert option to override.
    • setters. Use the runSettersOnQuery option to override.

    findAndModify helpers support limited validation. You can
    enable these by setting the runValidators options,
    respectively.

    If you need full-fledged validation, use the traditional approach of first
    retrieving the document.

    1. Model.findById(id, function (err, doc) {
    2.   if (err) ..
    3.   doc.name = 'jason bourne';
    4.   doc.save(callback);
    5. });

    Model.findOneAndUpdate([conditions], [update], [options], [options.lean], [callback])

    Issues a mongodb findAndModify update command.

    show code

    1. Model.findOneAndUpdate = function(conditions, update, options, callback) {
    2.   if (typeof options === 'function') {
    3.     callback = options;
    4.     options = null;
    5.   } else if (arguments.length === 1) {
    6.     if (typeof conditions === 'function') {
    7.       var msg = 'Model.findOneAndUpdate(): First argument must not be a function.
    9. '
    10.           + '  ' + this.modelName + '.findOneAndUpdate(conditions, update, options, callback)
    11. '
    12.           + '  ' + this.modelName + '.findOneAndUpdate(conditions, update, options)
    13. '
    14.           + '  ' + this.modelName + '.findOneAndUpdate(conditions, update)
    15. '
    16.           + '  ' + this.modelName + '.findOneAndUpdate(update)
    17. '
    18.           + '  ' + this.modelName + '.findOneAndUpdate()
    19. ';
    20.       throw new TypeError(msg);
    21.     }
    22.     update = conditions;
    23.     conditions = undefined;
    24.   }
    25.   if (callback) {
    26.     callback = this.$wrapCallback(callback);
    27.   }
    29.   var fields;
    30.   if (options && options.fields) {
    31.     fields = options.fields;
    32.   }
    34.   var retainKeyOrder = get(options, 'retainKeyOrder') ||
    35.     get(this, 'schema.options.retainKeyOrder') ||
    36.     false;
    37.   update = utils.clone(update, {
    38.     depopulate: true,
    39.     _isNested: true,
    40.     retainKeyOrder: retainKeyOrder
    41.   });
    42.   if (this.schema.options.versionKey && options && options.upsert) {
    43.     if (options.overwrite) {
    44.       update[this.schema.options.versionKey] = 0;
    45.     } else {
    46.       if (!update.$setOnInsert) {
    47.         update.$setOnInsert = {};
    48.       }
    49.       update.$setOnInsert[this.schema.options.versionKey] = 0;
    50.     }
    51.   }
    53.   var mq = new this.Query({}, {}, this, this.collection);
    54.   mq.select(fields);
    56.   return mq.findOneAndUpdate(conditions, update, options, callback);
    57. };

    Parameters:

    Returns:

    See:

    Finds a matching document, updates it according to the update arg, passing any options, and returns the found document (if any) to the callback. The query executes immediately if callback is passed else a Query object is returned.

    Options:

    • new: bool - if true, return the modified document rather than the original. defaults to false (changed in 4.0)
    • upsert: bool - creates the object if it doesn’t exist. defaults to false.
    • fields: {Object|String} - Field selection. Equivalent to .select(fields).findOneAndUpdate()
    • maxTimeMS: puts a time limit on the query - requires mongodb >= 2.6.0
    • sort: if multiple docs are found by the conditions, sets the sort order to choose which doc to update
    • runValidators: if true, runs update validators on this command. Update validators validate the update operation against the model’s schema.
    • setDefaultsOnInsert: if this and upsert are true, mongoose will apply the defaults specified in the model’s schema if a new document is created. This option only works on MongoDB >= 2.4 because it relies on MongoDB’s $setOnInsert operator.
    • passRawResult: if true, passes the raw result from the MongoDB driver as the third callback parameter
    • strict: overwrites the schema’s strict mode option for this update
    • runSettersOnQuery: bool - if true, run all setters defined on the associated model’s schema for all fields defined in the query and the update.

    Examples:

    1. A.findOneAndUpdate(conditions, update, options, callback) // executes
    2. A.findOneAndUpdate(conditions, update, options)  // returns Query
    3. A.findOneAndUpdate(conditions, update, callback) // executes
    4. A.findOneAndUpdate(conditions, update)           // returns Query
    5. A.findOneAndUpdate()                             // returns Query

    Note:

    All top level update keys which are not atomic operation names are treated as set operations:

    Example:

    1. var query = { name: 'borne' };
    2. Model.findOneAndUpdate(query, { name: 'jason bourne' }, options, callback)
    4. // is sent as
    5. Model.findOneAndUpdate(query, { $set: { name: 'jason bourne' }}, options, callback)

    This helps prevent accidentally overwriting your document with { name: 'jason bourne' }.

    Note:

    Values are cast to their appropriate types when using the findAndModify helpers.
    However, the below are not executed by default.

    • defaults. Use the setDefaultsOnInsert option to override.
    • setters. Use the runSettersOnQuery option to override.

    findAndModify helpers support limited validation. You can
    enable these by setting the runValidators options,
    respectively.

    If you need full-fledged validation, use the traditional approach of first
    retrieving the document.

    1. Model.findById(id, function (err, doc) {
    2.   if (err) ..
    3.   doc.name = 'jason bourne';
    4.   doc.save(callback);
    5. });

    Model.geoNear(GeoJSON, options, [callback])

    geoNear support for Mongoose

    show code

    1. Model.geoNear = function(near, options, callback) {
    2.   if (typeof options === 'function') {
    3.     callback = options;
    4.     options = {};
    5.   }
    7.   if (callback) {
    8.     callback = this.$wrapCallback(callback);
    9.   }
    11.   var _this = this;
    12.   var Promise = PromiseProvider.get();
    13.   if (!near) {
    14.     return new Promise.ES6(function(resolve, reject) {
    15.       var error = new Error('Must pass a near option to geoNear');
    16.       reject(error);
    17.       callback && callback(error);
    18.     });
    19.   }
    21.   var x;
    22.   var y;
    23.   var schema = this.schema;
    25.   return new Promise.ES6(function(resolve, reject) {
    26.     var handler = function(err, res) {
    27.       if (err) {
    28.         reject(err);
    29.         callback && callback(err);
    30.         return;
    31.       }
    32.       if (options.lean) {
    33.         resolve(res.results, res.stats);
    34.         callback && callback(null, res.results, res.stats);
    35.         return;
    36.       }
    38.       var count = res.results.length;
    39.       // if there are no results, fulfill the promise now
    40.       if (count === 0) {
    41.         resolve(res.results, res.stats);
    42.         callback && callback(null, res.results, res.stats);
    43.         return;
    44.       }
    46.       var errSeen = false;
    48.       function init(err) {
    49.         if (err && !errSeen) {
    50.           errSeen = true;
    51.           reject(err);
    52.           callback && callback(err);
    53.           return;
    54.         }
    55.         if (--count <= 0) {
    56.           resolve(res.results, res.stats);
    57.           callback && callback(null, res.results, res.stats);
    58.         }
    59.       }
    61.       for (var i = 0; i < res.results.length; i++) {
    62.         var temp = res.results[i].obj;
    63.         res.results[i].obj = new _this();
    64.         res.results[i].obj.init(temp, init);
    65.       }
    66.     };
    68.     if (options.query != null) {
    69.       options.query = utils.clone(options.query, { retainKeyOrder: 1 });
    70.       cast(schema, options.query);
    71.     }
    73.     if (Array.isArray(near)) {
    74.       if (near.length !== 2) {
    75.         var error = new Error('If using legacy coordinates, must be an array ' +
    76.             'of size 2 for geoNear');
    77.         reject(error);
    78.         callback && callback(error);
    79.         return;
    80.       }
    81.       x = near[0];
    82.       y = near[1];
    83.       _this.collection.geoNear(x, y, options, handler);
    84.     } else {
    85.       if (near.type !== 'Point' || !Array.isArray(near.coordinates)) {
    86.         error = new Error('Must pass either a legacy coordinate array or ' +
    87.             'GeoJSON Point to geoNear');
    88.         reject(error);
    89.         callback && callback(error);
    90.         return;
    91.       }
    93.       _this.collection.geoNear(near, options, handler);
    94.     }
    95.   });
    96. };

    Parameters:

    • GeoJSON <Object, Array> point or legacy coordinate pair [x,y] to search near
    • options <Object> for the query
    • [callback] <Function> optional callback for the query

    Returns:

    See:

    This function does not trigger any middleware. In particular, this
    bypasses find() middleware.

    Options:

    • lean {Boolean} return the raw object
    • All options supported by the driver are also supported

    Example:

    1. // Legacy point
    2. Model.geoNear([1,3], { maxDistance : 5, spherical : true }, function(err, results, stats) {
    3.    console.log(results);
    4. });
    6. // geoJson
    7. var point = { type : "Point", coordinates : [9,9] };
    8. Model.geoNear(point, { maxDistance : 5, spherical : true }, function(err, results, stats) {
    9.    console.log(results);
    10. });

    Model.geoSearch(conditions, [options], [options.lean], [callback])

    Implements $geoSearch functionality for Mongoose

    show code

    1. Model.geoSearch = function(conditions, options, callback) {
    2.   if (typeof options === 'function') {
    3.     callback = options;
    4.     options = {};
    5.   }
    6.   if (callback) {
    7.     callback = this.$wrapCallback(callback);
    8.   }
    10.   var _this = this;
    11.   var Promise = PromiseProvider.get();
    12.   return new Promise.ES6(function(resolve, reject) {
    13.     var error;
    14.     if (conditions === undefined || !utils.isObject(conditions)) {
    15.       error = new Error('Must pass conditions to geoSearch');
    16.     } else if (!options.near) {
    17.       error = new Error('Must specify the near option in geoSearch');
    18.     } else if (!Array.isArray(options.near)) {
    19.       error = new Error('near option must be an array [x, y]');
    20.     }
    22.     if (error) {
    23.       callback && callback(error);
    24.       reject(error);
    25.       return;
    26.     }
    28.     // send the conditions in the options object
    29.     options.search = conditions;
    31.     _this.collection.geoHaystackSearch(options.near[0], options.near[1], options, function(err, res) {
    32.       // have to deal with driver problem. Should be fixed in a soon-ish release
    33.       // (7/8/2013)
    34.       if (err) {
    35.         callback && callback(err);
    36.         reject(err);
    37.         return;
    38.       }
    40.       var count = res.results.length;
    41.       if (options.lean || count === 0) {
    42.         callback && callback(null, res.results, res.stats);
    43.         resolve(res.results, res.stats);
    44.         return;
    45.       }
    47.       var errSeen = false;
    49.       function init(err) {
    50.         if (err && !errSeen) {
    51.           callback && callback(err);
    52.           reject(err);
    53.           return;
    54.         }
    56.         if (!--count && !errSeen) {
    57.           callback && callback(null, res.results, res.stats);
    58.           resolve(res.results, res.stats);
    59.         }
    60.       }
    62.       for (var i = 0; i < res.results.length; i++) {
    63.         var temp = res.results[i];
    64.         res.results[i] = new _this();
    65.         res.results[i].init(temp, {}, init);
    66.       }
    67.     });
    68.   });
    69. };

    Parameters:

    Returns:

    See:

    This function does not trigger any middleware

    Example:

    1. var options = { near: [10, 10], maxDistance: 5 };
    2. Locations.geoSearch({ type : "house" }, options, function(err, res) {
    3.   console.log(res);
    4. });

    Options:

    • near {Array} x,y point to search for
    • maxDistance {Number} the maximum distance from the point near that a result can be
    • limit {Number} The maximum number of results to return
    • lean {Boolean} return the raw object instead of the Mongoose Model

    Model.hydrate(obj)

    Shortcut for creating a new Document from existing raw data, pre-saved in the DB.
    The document returned has no paths marked as modified initially.

    show code

    1. Model.hydrate = function(obj) {
    2.   var model = require('./queryhelpers').createModel(this, obj);
    3.   model.init(obj);
    4.   return model;
    5. };

    Parameters:

    Returns:

    Example:

    1. // hydrate previous data into a Mongoose document
    2. var mongooseCandy = Candy.hydrate({ _id: '54108337212ffb6d459f854c', type: 'jelly bean' });

    Model.init([callback])

    Performs any async initialization of this model against MongoDB. Currently,
    this function is only responsible for building indexes,
    unless autoIndex is turned off.

    show code

    1. Model.init = function init(callback) {
    2.   this.schema.emit('init', this);
    4.   if (this.$init) {
    5.     return this.$init;
    6.   }
    8.   var _this = this;
    9.   var Promise = PromiseProvider.get();
    10.   this.$init = new Promise.ES6(function(resolve, reject) {
    11.     if ((_this.schema.options.autoIndex) ||
    12.         (_this.schema.options.autoIndex == null && _this.db.config.autoIndex)) {
    13.       _this.ensureIndexes({ _automatic: true, __noPromise: true }, function(error) {
    14.         if (error) {
    15.           callback && callback(error);
    16.           return reject(error);
    17.         }
    18.         callback && callback(null, _this);
    19.         resolve(_this);
    20.       });
    21.     } else {
    22.       resolve(_this);
    23.     }
    24.   });
    26.   return this.$init;
    27. };

    Parameters:

    This function is called automatically, so you don’t need to call it.
    This function is also idempotent, so you may call it to get back a promise
    that will resolve when your indexes are finished building as an alternative
    to MyModel.on('index')

    Example:

    1. var eventSchema = new Schema({ thing: { type: 'string', unique: true }})
    2. // This calls `Event.init()` implicitly, so you don't need to call
    3. // `Event.init()` on your own.
    4. var Event = mongoose.model('Event', eventSchema);
    6. Event.init().then(function(Event) {
    7.   // You can also use `Event.on('index')` if you prefer event emitters
    8.   // over promises.
    9.   console.log('Indexes are done building!');
    10. });

    Model.insertMany(doc(s), [options], [options.ordered, [options.rawResult, [callback])

    Shortcut for validating an array of documents and inserting them into
    MongoDB if they’re all valid. This function is faster than .create()
    because it only sends one operation to the server, rather than one for each
    document.

    show code

    1. Model.insertMany = function(arr, options, callback) {
    2.   var _this = this;
    3.   if (typeof options === 'function') {
    4.     callback = options;
    5.     options = null;
    6.   }
    7.   if (callback) {
    8.     callback = this.$wrapCallback(callback);
    9.   }
    10.   callback = callback || utils.noop;
    11.   options = options || {};
    12.   var limit = get(options, 'limit', 1000);
    13.   var rawResult = get(options, 'rawResult', false);
    14.   var ordered = get(options, 'ordered', true);
    16.   if (!Array.isArray(arr)) {
    17.     arr = [arr];
    18.   }
    20.   var toExecute = [];
    21.   var validationErrors = [];
    22.   arr.forEach(function(doc) {
    23.     toExecute.push(function(callback) {
    24.       doc = new _this(doc);
    25.       doc.validate({ __noPromise: true }, function(error) {
    26.         if (error) {
    27.           // Option `ordered` signals that insert should be continued after reaching
    28.           // a failing insert. Therefore we delegate "null", meaning the validation
    29.           // failed. It's up to the next function to filter out all failed models
    30.           if (ordered === false) {
    31.             validationErrors.push(error);
    32.             return callback(null, null);
    33.           }
    34.           return callback(error);
    35.         }
    36.         callback(null, doc);
    37.       });
    38.     });
    39.   });
    41.   parallelLimit(toExecute, limit, function(error, docs) {
    42.     if (error) {
    43.       callback && callback(error);
    44.       return;
    45.     }
    46.     // We filter all failed pre-validations by removing nulls
    47.     var docAttributes = docs.filter(function(doc) {
    48.       return doc != null;
    49.     });
    50.     // Quickly escape while there aren't any valid docAttributes
    51.     if (docAttributes.length < 1) {
    52.       callback(null, []);
    53.       return;
    54.     }
    55.     var docObjects = docAttributes.map(function(doc) {
    56.       if (doc.schema.options.versionKey) {
    57.         doc[doc.schema.options.versionKey] = 0;
    58.       }
    59.       if (doc.initializeTimestamps) {
    60.         return doc.initializeTimestamps().toObject(INSERT_MANY_CONVERT_OPTIONS);
    61.       }
    62.       return doc.toObject(INSERT_MANY_CONVERT_OPTIONS);
    63.     });
    65.     _this.collection.insertMany(docObjects, options, function(error, res) {
    66.       if (error) {
    67.         callback && callback(error);
    68.         return;
    69.       }
    70.       for (var i = 0; i < docAttributes.length; ++i) {
    71.         docAttributes[i].isNew = false;
    72.         docAttributes[i].emit('isNew', false);
    73.         docAttributes[i].constructor.emit('isNew', false);
    74.       }
    75.       if (rawResult) {
    76.         if (ordered === false) {
    77.           // Decorate with mongoose validation errors in case of unordered,
    78.           // because then still do `insertMany()`
    79.           res.mongoose = {
    80.             validationErrors: validationErrors
    81.           };
    82.         }
    83.         return callback(null, res);
    84.       }
    85.       callback(null, docAttributes);
    86.     });
    87.   });
    88. };

    Parameters:

    Returns:

    Mongoose always validates each document before sending insertMany
    to MongoDB. So if one document has a validation error, no documents will
    be saved, unless you set
    the ordered option to false.

    This function does not trigger save middleware.

    This function triggers the following middleware

    • insertMany()

    Example:

    1. var arr = [{ name: 'Star Wars' }, { name: 'The Empire Strikes Back' }];
    2. Movies.insertMany(arr, function(error, docs) {});

    Model.mapReduce(o, [callback])

    Executes a mapReduce command.

    show code

    1. Model.mapReduce = function mapReduce(o, callback) {
    2.   var _this = this;
    3.   if (callback) {
    4.     callback = this.$wrapCallback(callback);
    5.   }
    6.   var resolveToObject = o.resolveToObject;
    7.   var Promise = PromiseProvider.get();
    8.   return new Promise.ES6(function(resolve, reject) {
    9.     if (!Model.mapReduce.schema) {
    10.       var opts = {noId: true, noVirtualId: true, strict: false};
    11.       Model.mapReduce.schema = new Schema({}, opts);
    12.     }
    14.     if (!o.out) o.out = {inline: 1};
    15.     if (o.verbose !== false) o.verbose = true;
    17.     o.map = String(o.map);
    18.     o.reduce = String(o.reduce);
    20.     if (o.query) {
    21.       var q = new _this.Query(o.query);
    22.       q.cast(_this);
    23.       o.query = q._conditions;
    24.       q = undefined;
    25.     }
    27.     _this.collection.mapReduce(null, null, o, function(err, ret, stats) {
    28.       if (err) {
    29.         callback && callback(err);
    30.         reject(err);
    31.         return;
    32.       }
    34.       if (ret.findOne && ret.mapReduce) {
    35.         // returned a collection, convert to Model
    36.         var model = Model.compile(
    37.             '_mapreduce_' + ret.collectionName
    38.             , Model.mapReduce.schema
    39.             , ret.collectionName
    40.             , _this.db
    41.             , _this.base);
    43.         model._mapreduce = true;
    45.         callback && callback(null, model, stats);
    46.         return resolveToObject ? resolve({
    47.           model: model,
    48.           stats: stats
    49.         }) : resolve(model, stats);
    50.       }
    52.       callback && callback(null, ret, stats);
    53.       if (resolveToObject) {
    54.         return resolve({ model: ret, stats: stats });
    55.       }
    56.       resolve(ret, stats);
    57.     });
    58.   });
    59. };

    Parameters:

    • o <Object> an object specifying map-reduce options
    • [callback] <Function> optional callback

    Returns:

    See:

    o is an object specifying all mapReduce options as well as the map and reduce functions. All options are delegated to the driver implementation. See node-mongodb-native mapReduce() documentation for more detail about options.

    This function does not trigger any middleware.

    Example:

    1. var o = {};
    2. o.map = function () { emit(this.name, 1) }
    3. o.reduce = function (k, vals) { return vals.length }
    4. User.mapReduce(o, function (err, results) {
    5.   console.log(results)
    6. })

    Other options:

    • query {Object} query filter object.
    • sort {Object} sort input objects using this key
    • limit {Number} max number of documents
    • keeptemp {Boolean, default:false} keep temporary data
    • finalize {Function} finalize function
    • scope {Object} scope variables exposed to map/reduce/finalize during execution
    • jsMode {Boolean, default:false} it is possible to make the execution stay in JS. Provided in MongoDB > 2.0.X
    • verbose {Boolean, default:false} provide statistics on job execution time.
    • readPreference {String}
    • out* {Object, default: {inline:1}} sets the output target for the map reduce job.

    * out options:

    • {inline:1} the results are returned in an array
    • {replace: 'collectionName'} add the results to collectionName: the results replace the collection
    • {reduce: 'collectionName'} add the results to collectionName: if dups are detected, uses the reducer / finalize functions
    • {merge: 'collectionName'} add the results to collectionName: if dups exist the new docs overwrite the old

    If options.out is set to replace, merge, or reduce, a Model instance is returned that can be used for further querying. Queries run against this model are all executed with the lean option; meaning only the js object is returned and no Mongoose magic is applied (getters, setters, etc).

    Example:

    1. var o = {};
    2. o.map = function () { emit(this.name, 1) }
    3. o.reduce = function (k, vals) { return vals.length }
    4. o.out = { replace: 'createdCollectionNameForResults' }
    5. o.verbose = true;
    7. User.mapReduce(o, function (err, model, stats) {
    8.   console.log('map reduce took %d ms', stats.processtime)
    9.   model.find().where('value').gt(10).exec(function (err, docs) {
    10.     console.log(docs);
    11.   });
    12. })
    14. // `mapReduce()` returns a promise. However, ES6 promises can only
    15. // resolve to exactly one value,
    16. o.resolveToObject = true;
    17. var promise = User.mapReduce(o);
    18. promise.then(function (res) {
    19.   var model = res.model;
    20.   var stats = res.stats;
    21.   console.log('map reduce took %d ms', stats.processtime)
    22.   return model.find().where('value').gt(10).exec();
    23. }).then(function (docs) {
    24.    console.log(docs);
    25. }).then(null, handleError).end()

    Model.populate(docs, options, [callback(err,doc)])

    Populates document references.

    show code

    1. Model.populate = function(docs, paths, callback) {
    2.   var _this = this;
    3.   if (callback) {
    4.     callback = this.$wrapCallback(callback);
    5.   }
    7.   // normalized paths
    8.   var noPromise = paths && !!paths.__noPromise;
    9.   paths = utils.populate(paths);
    11.   // data that should persist across subPopulate calls
    12.   var cache = {};
    14.   if (noPromise) {
    15.     _populate(this, docs, paths, cache, callback);
    16.   } else {
    17.     var Promise = PromiseProvider.get();
    18.     return new Promise.ES6(function(resolve, reject) {
    19.       _populate(_this, docs, paths, cache, function(error, docs) {
    20.         if (error) {
    21.           callback && callback(error);
    22.           reject(error);
    23.         } else {
    24.           callback && callback(null, docs);
    25.           resolve(docs);
    26.         }
    27.       });
    28.     });
    29.   }
    30. };

    Parameters:

    • docs <Document, Array> Either a single document or array of documents to populate.
    • options <Object> A hash of key/val (path, options) used for population.
    • [callback(err,doc)] <Function> Optional callback, executed upon completion. Receives <code>err</code> and the <code>doc(s)</code>.

    Returns:

    Available options:

    • path: space delimited path(s) to populate
    • select: optional fields to select
    • match: optional query conditions to match
    • model: optional name of the model to use for population
    • options: optional query options like sort, limit, etc

    Examples:

    1. // populates a single object
    2. User.findById(id, function (err, user) {
    3.   var opts = [
    4.       { path: 'company', match: { x: 1 }, select: 'name' }
    5.     , { path: 'notes', options: { limit: 10 }, model: 'override' }
    6.   ]
    8.   User.populate(user, opts, function (err, user) {
    9.     console.log(user);
    10.   });
    11. });
    13. // populates an array of objects
    14. User.find(match, function (err, users) {
    15.   var opts = [{ path: 'company', match: { x: 1 }, select: 'name' }]
    17.   var promise = User.populate(users, opts);
    18.   promise.then(console.log).end();
    19. })
    21. // imagine a Weapon model exists with two saved documents:
    22. //   { _id: 389, name: 'whip' }
    23. //   { _id: 8921, name: 'boomerang' }
    24. // and this schema:
    25. // new Schema({
    26. //   name: String,
    27. //   weapon: { type: ObjectId, ref: 'Weapon' }
    28. // });
    30. var user = { name: 'Indiana Jones', weapon: 389 }
    31. Weapon.populate(user, { path: 'weapon', model: 'Weapon' }, function (err, user) {
    32.   console.log(user.weapon.name) // whip
    33. })
    35. // populate many plain objects
    36. var users = [{ name: 'Indiana Jones', weapon: 389 }]
    37. users.push({ name: 'Batman', weapon: 8921 })
    38. Weapon.populate(users, { path: 'weapon' }, function (err, users) {
    39.   users.forEach(function (user) {
    40.     console.log('%s uses a %s', users.name, user.weapon.name)
    41.     // Indiana Jones uses a whip
    42.     // Batman uses a boomerang
    43.   });
    44. });
    45. // Note that we didn't need to specify the Weapon model because
    46. // it is in the schema's ref

    Model.remove(conditions, [callback])

    Removes all documents that match conditions from the collection.
    To remove just the first document that matches conditions, set the single
    option to true.

    show code

    1. Model.remove = function remove(conditions, callback) {
    2.   if (typeof conditions === 'function') {
    3.     callback = conditions;
    4.     conditions = {};
    5.   }
    7.   // get the mongodb collection object
    8.   var mq = new this.Query({}, {}, this, this.collection);
    10.   if (callback) {
    11.     callback = this.$wrapCallback(callback);
    12.   }
    14.   return mq.remove(conditions, callback);
    15. };

    Parameters:

    Returns:

    Example:

    1. Character.remove({ name: 'Eddard Stark' }, function (err) {});

    Note:

    This method sends a remove command directly to MongoDB, no Mongoose documents
    are involved. Because no Mongoose documents are involved, no middleware
    (hooks) are executed    .

    Model.replaceOne(conditions, doc, [options], [callback])

    Same as update(), except MongoDB replace the existing document with the
    given document (no atomic operators like $set).

    show code

    1. Model.replaceOne = function replaceOne(conditions, doc, options, callback) {
    2.   return _update(this, 'replaceOne', conditions, doc, options, callback);
    3. };

    Parameters:

    Returns:

    This function triggers the following middleware

    • replaceOne()

    Model.translateAliases(raw)

    Translate any aliases fields/conditions so the final query or document object is pure

    show code

    1. Model.translateAliases = function translateAliases(fields) {
    2.   var aliases = this.schema.aliases;
    4.   if (typeof fields === 'object') {
    5.     // Fields is an object (query conditions or document fields)
    6.     for (var key in fields) {
    7.       if (aliases[key]) {
    8.         fields[aliases[key]] = fields[key];
    9.         delete fields[key];
    10.       }
    11.     }
    13.     return fields;
    14.   } else {
    15.     // Don't know typeof fields
    16.     return fields;
    17.   }
    18. };

    Parameters:

    • raw <Object> fields/conditions that may contain aliased keys

    Returns:

    • <Object> the translated ‘pure’ fields/conditions

    Example:

    1. Character
    2.   .find(Character.translateAliases({
    3.     '名': 'Eddard Stark' // Alias for 'name'
    4.   })
    5.   .exec(function(err, characters) {})

    Note:

    Only translate arguments of object type anything else is returned raw

    Model.update(conditions, doc, [options], [callback])

    Updates one document in the database without returning it.

    show code

    1. Model.update = function update(conditions, doc, options, callback) {
    2.   return _update(this, 'update', conditions, doc, options, callback);
    3. };

    Parameters:

    Returns:

    See:

    This function triggers the following middleware

    • update()

    Examples:

    1. MyModel.update({ age: { $gt: 18 } }, { oldEnough: true }, fn);
    2. MyModel.update({ name: 'Tobi' }, { ferret: true }, { multi: true }, function (err, raw) {
    3.   if (err) return handleError(err);
    4.   console.log('The raw response from Mongo was ', raw);
    5. });

    Valid options:

    • safe (boolean) safe mode (defaults to value set in schema (true))
    • upsert (boolean) whether to create the doc if it doesn’t match (false)
    • multi (boolean) whether multiple documents should be updated (false)
    • runValidators: if true, runs update validators on this command. Update validators validate the update operation against the model’s schema.
    • setDefaultsOnInsert: if this and upsert are true, mongoose will apply the defaults specified in the model’s schema if a new document is created. This option only works on MongoDB >= 2.4 because it relies on MongoDB’s $setOnInsert operator.
    • strict (boolean) overrides the strict option for this update
    • overwrite (boolean) disables update-only mode, allowing you to overwrite the doc (false)

    All update values are cast to their appropriate SchemaTypes before being sent.

    The callback function receives (err, rawResponse).

    • err is the error if any occurred
    • rawResponse is the full response from Mongo

    Note:

    All top level keys which are not atomic operation names are treated as set operations:

    Example:

    1. var query = { name: 'borne' };
    2. Model.update(query, { name: 'jason bourne' }, options, callback)
    4. // is sent as
    5. Model.update(query, { $set: { name: 'jason bourne' }}, options, callback)
    6. // if overwrite option is false. If overwrite is true, sent without the $set wrapper.

    This helps prevent accidentally overwriting all documents in your collection with { name: 'jason bourne' }.

    Note:

    Be careful to not use an existing model instance for the update clause (this won’t work and can cause weird behavior like infinite loops). Also, ensure that the update clause does not have an _id property, which causes Mongo to return a “Mod on _id not allowed” error.

    Note:

    To update documents without waiting for a response from MongoDB, do not pass a callback, then call exec on the returned Query:

    1. Comment.update({ _id: id }, { $set: { text: 'changed' }}).exec();

    Note:

    Although values are casted to their appropriate types when using update, the following are not applied:

    • defaults
    • setters
    • validators
    • middleware

    If you need those features, use the traditional approach of first retrieving the document.

    1. Model.findOne({ name: 'borne' }, function (err, doc) {
    2.   if (err) ..
    3.   doc.name = 'jason bourne';
    4.   doc.save(callback);
    5. })

    Model.updateMany(conditions, doc, [options], [callback])

    Same as update(), except MongoDB will update all documents that match
    criteria (as opposed to just the first one) regardless of the value of
    the multi option.

    show code

    1. Model.updateMany = function updateMany(conditions, doc, options, callback) {
    2.   return _update(this, 'updateMany', conditions, doc, options, callback);
    3. };

    Parameters:

    Returns:

    Note updateMany will not fire update middleware. Use pre('updateMany')
    and post('updateMany') instead.

    This function triggers the following middleware

    • updateMany()

    Model.updateOne(conditions, doc, [options], [callback])

    Same as update(), except MongoDB will update only the first document that
    matches criteria regardless of the value of the multi option.

    show code

    1. Model.updateOne = function updateOne(conditions, doc, options, callback) {
    2.   return _update(this, 'updateOne', conditions, doc, options, callback);
    3. };

    Parameters:

    Returns:

    This function triggers the following middleware

    • updateOne()

    Model.where(path, [val])

    Creates a Query, applies the passed conditions, and returns the Query.

    show code

    1. Model.where = function where(path, val) {
    2.   void val; // eslint
    3.   // get the mongodb collection object
    4.   var mq = new this.Query({}, {}, this, this.collection).find({});
    5.   return mq.where.apply(mq, arguments);
    6. };

    Parameters:

    Returns:

    For example, instead of writing:

    1. User.find({age: {$gte: 21, $lte: 65}}, callback);

    we can instead write:

    1. User.where('age').gte(21).lte(65).exec(callback);

    Since the Query class also supports where you can continue chaining

    1. User
    2. .where('age').gte(21).lte(65)
    3. .where('name', /^b/i)
    4. ... etc

    Model#$where

    Additional properties to attach to the query when calling save() and
    isNew is false.

    show code

    1. Model.prototype.$where;

    Model#base

    Base Mongoose instance the model uses.

    show code

    1. Model.base;

    Model#baseModelName

    If this is a discriminator model, baseModelName is the name of
    the base model.

    show code

    1. Model.prototype.baseModelName;
    3. Model.prototype.$__handleSave = function(options, callback) {
    4.   var _this = this;
    5.   var i;
    6.   var keys;
    7.   var len;
    8.   if (!options.safe && this.schema.options.safe) {
    9.     options.safe = this.schema.options.safe;
    10.   }
    11.   if (typeof options.safe === 'boolean') {
    12.     options.safe = null;
    13.   }
    14.   var safe = options.safe ? utils.clone(options.safe, { retainKeyOrder: true }) : options.safe;
    16.   if (this.isNew) {
    17.     // send entire doc
    18.     var toObjectOptions = {};
    20.     toObjectOptions.retainKeyOrder = this.schema.options.retainKeyOrder;
    21.     toObjectOptions.depopulate = 1;
    22.     toObjectOptions._skipDepopulateTopLevel = true;
    23.     toObjectOptions.transform = false;
    24.     toObjectOptions.flattenDecimals = false;
    26.     var obj = this.toObject(toObjectOptions);
    28.     if ((obj || {})._id === void 0) {
    29.       // documents must have an _id else mongoose won't know
    30.       // what to update later if more changes are made. the user
    31.       // wouldn't know what _id was generated by mongodb either
    32.       // nor would the ObjectId generated my mongodb necessarily
    33.       // match the schema definition.
    34.       setTimeout(function() {
    35.         callback(new Error('document must have an _id before saving'));
    36.       }, 0);
    37.       return;
    38.     }
    40.     this.$__version(true, obj);
    41.     this.collection.insert(obj, safe, function(err, ret) {
    42.       if (err) {
    43.         _this.isNew = true;
    44.         _this.emit('isNew', true);
    45.         _this.constructor.emit('isNew', true);
    47.         callback(err);
    48.         return;
    49.       }
    51.       callback(null, ret);
    52.     });
    53.     this.$__reset();
    54.     this.isNew = false;
    55.     this.emit('isNew', false);
    56.     this.constructor.emit('isNew', false);
    57.     // Make it possible to retry the insert
    58.     this.$__.inserting = true;
    59.   } else {
    60.     // Make sure we don't treat it as a new object on error,
    61.     // since it already exists
    62.     this.$__.inserting = false;
    64.     var delta = this.$__delta();
    66.     if (delta) {
    67.       if (delta instanceof Error) {
    68.         callback(delta);
    69.         return;
    70.       }
    72.       var where = this.$__where(delta[0]);
    73.       if (where instanceof Error) {
    74.         callback(where);
    75.         return;
    76.       }
    78.       if (this.$where) {
    79.         keys = Object.keys(this.$where);
    80.         len = keys.length;
    81.         for (i = 0; i < len; ++i) {
    82.           where[keys[i]] = this.$where[keys[i]];
    83.         }
    84.       }
    86.       this.collection.update(where, delta[1], safe, function(err, ret) {
    87.         if (err) {
    88.           callback(err);
    89.           return;
    90.         }
    91.         ret.$where = where;
    92.         callback(null, ret);
    93.       });
    94.     } else {
    95.       this.$__reset();
    96.       callback();
    97.       return;
    98.     }
    100.     this.emit('isNew', false);
    101.     this.constructor.emit('isNew', false);
    102.   }
    103. };

    Model#collection

    Collection the model uses.

    show code

    1. Model.prototype.collection;

    Model#db

    Connection the model uses.

    show code

    1. Model.prototype.db;

    Model#discriminators

    Registered discriminators for this model.

    show code

    1. Model.discriminators;

    Model#modelName

    The name of the model

    show code

    1. Model.prototype.modelName;

    Model#schema

    Schema the model uses.

    show code

    1. Model.schema;

  • query.js

    Query#_applyPaths()

    Applies schematype selected options to this query.

    show code

    1. Query.prototype._applyPaths = function applyPaths() {
    2.   this._fields = this._fields || {};
    3.   helpers.applyPaths(this._fields, this.model.schema);
    4.   selectPopulatedFields(this);
    5. };

    Query#_castFields(fields)

    Casts selected field arguments for field selection with mongo 2.2

    Parameters:

    See:

    1. query.select({ ids: { $elemMatch: { $in: [hexString] }})

    show code

    1. Query.prototype._castFields = function _castFields(fields) {
    2.   var selected,
    3.       elemMatchKeys,
    4.       keys,
    5.       key,
    6.       out,
    7.       i;
    9.   if (fields) {
    10.     keys = Object.keys(fields);
    11.     elemMatchKeys = [];
    12.     i = keys.length;
    14.     // collect $elemMatch args
    15.     while (i--) {
    16.       key = keys[i];
    17.       if (fields[key].$elemMatch) {
    18.         selected || (selected = {});
    19.         selected[key] = fields[key];
    20.         elemMatchKeys.push(key);
    21.       }
    22.     }
    23.   }
    25.   if (selected) {
    26.     // they passed $elemMatch, cast em
    27.     try {
    28.       out = this.cast(this.model, selected);
    29.     } catch (err) {
    30.       return err;
    31.     }
    33.     // apply the casted field args
    34.     i = elemMatchKeys.length;
    35.     while (i--) {
    36.       key = elemMatchKeys[i];
    37.       fields[key] = out[key];
    38.     }
    39.   }
    41.   return fields;
    42. };

    Query#_count([callback])

    Thunk around count()

    Parameters:

    See:

    show code

    1. Query.prototype._count = function(callback) {
    2.   try {
    3.     this.cast(this.model);
    4.   } catch (err) {
    5.     this.error(err);
    6.   }
    8.   if (this.error()) {
    9.     return callback(this.error());
    10.   }
    12.   var conds = this._conditions;
    13.   var options = this._optionsForExec();
    15.   this._collection.count(conds, options, utils.tick(callback));
    16. };

    Query#_find([callback])

    Thunk around find()

    Parameters:

    Returns:

    show code

    1. Query.prototype._find = function(callback) {
    2.   this._castConditions();
    4.   if (this.error() != null) {
    5.     callback(this.error());
    6.     return this;
    7.   }
    9.   this._applyPaths();
    10.   this._fields = this._castFields(this._fields);
    12.   var fields = this._fieldsForExec();
    13.   var mongooseOptions = this._mongooseOptions;
    14.   var _this = this;
    15.   var userProvidedFields = _this._userProvidedFields || {};
    17.   var cb = function(err, docs) {
    18.     if (err) {
    19.       return callback(err);
    20.     }
    22.     if (docs.length === 0) {
    23.       return callback(null, docs);
    24.     }
    26.     if (!mongooseOptions.populate) {
    27.       return !!mongooseOptions.lean === true
    28.           ? callback(null, docs)
    29.           : completeMany(_this.model, docs, fields, userProvidedFields, null, callback);
    30.     }
    32.     var pop = helpers.preparePopulationOptionsMQ(_this, mongooseOptions);
    33.     pop.__noPromise = true;
    34.     _this.model.populate(docs, pop, function(err, docs) {
    35.       if (err) return callback(err);
    36.       return !!mongooseOptions.lean === true
    37.           ? callback(null, docs)
    38.           : completeMany(_this.model, docs, fields, userProvidedFields, pop, callback);
    39.     });
    40.   };
    42.   var options = this._optionsForExec();
    43.   options.fields = this._fieldsForExec();
    44.   var filter = this._conditions;
    45.   return this._collection.find(filter, options, cb);
    46. };

    Query#_findOne([callback])

    Thunk around findOne()

    Parameters:

    See:

    show code

    1. Query.prototype._findOne = function(callback) {
    2.   this._castConditions();
    4.   if (this.error()) {
    5.     return callback(this.error());
    6.   }
    8.   this._applyPaths();
    9.   this._fields = this._castFields(this._fields);
    11.   var options = this._mongooseOptions;
    12.   var projection = this._fieldsForExec();
    13.   var userProvidedFields = this._userProvidedFields || {};
    14.   var _this = this;
    16.   // don't pass in the conditions because we already merged them in
    17.   Query.base.findOne.call(_this, {}, function(err, doc) {
    18.     if (err) {
    19.       return callback(err);
    20.     }
    21.     if (!doc) {
    22.       return callback(null, null);
    23.     }
    25.     if (!options.populate) {
    26.       return !!options.lean === true
    27.           ? callback(null, doc)
    28.           : completeOne(_this.model, doc, null, {}, projection, userProvidedFields, null, callback);
    29.     }
    31.     var pop = helpers.preparePopulationOptionsMQ(_this, options);
    32.     pop.__noPromise = true;
    33.     _this.model.populate(doc, pop, function(err, doc) {
    34.       if (err) {
    35.         return callback(err);
    36.       }
    37.       return !!options.lean === true
    38.           ? callback(null, doc)
    39.           : completeOne(_this.model, doc, null, {}, projection, userProvidedFields, pop, callback);
    40.     });
    41.   });
    42. };

    Query#_optionsForExec(model)

    Returns default options for this query.

    Parameters:

    show code

    1. Query.prototype._optionsForExec = function(model) {
    2.   var options = Query.base._optionsForExec.call(this);
    4.   delete options.populate;
    5.   delete options.retainKeyOrder;
    6.   model = model || this.model;
    8.   if (!model) {
    9.     return options;
    10.   }
    12.   if (!('safe' in options) && model.schema.options.safe) {
    13.     options.safe = model.schema.options.safe;
    14.   }
    16.   if (!('readPreference' in options) && model.schema.options.read) {
    17.     options.readPreference = model.schema.options.read;
    18.   }
    20.   if (options.upsert !== void 0) {
    21.     options.upsert = !!options.upsert;
    22.   }
    24.   return options;
    25. };

    Query#$where(js)

    Specifies a javascript function or expression to pass to MongoDBs query system.

    Parameters:

    Returns:

    See:

    Example

    1. query.$where('this.comments.length === 10 || this.name.length === 5')
    3. // or
    5. query.$where(function () {
    6.   return this.comments.length === 10 || this.name.length === 5;
    7. })

    NOTE:

    Only use $where when you have a condition that cannot be met using other MongoDB operators like $lt.
    Be sure to read about all of its caveats before using.

    Query#all([path], val)

    Specifies an $all query condition.

    Parameters:

    See:

    When called with one argument, the most recent path passed to where() is used.

    Query#and(array)

    Specifies arguments for a $and condition.

    Parameters:

    • array <Array> array of conditions

    Returns:

    See:

    Example

    1. query.and([{ color: 'green' }, { status: 'ok' }])

    Query#batchSize(val)

    Specifies the batchSize option.

    Parameters:

    See:

    Example

    1. query.batchSize(100)

    Note

    Cannot be used with distinct()

    Query#box(val, Upper)

    Specifies a $box condition

    Parameters:

    Returns:

    See:

    Example

    1. var lowerLeft = [40.73083, -73.99756]
    2. var upperRight= [40.741404,  -73.988135]
    4. query.where('loc').within().box(lowerLeft, upperRight)
    5. query.box({ ll : lowerLeft, ur : upperRight })

    Query#canMerge(conds)

    Determines if conds can be merged using mquery().merge()

    Parameters:

    Returns:

    Query#cast(model, [obj])

    Casts this query to the schema of model

    Parameters:

    Returns:

    Note

    If obj is present, it is cast instead of this query.

    show code

    1. Query.prototype.cast = function(model, obj) {
    2.   obj || (obj = this._conditions);
    4.   try {
    5.     return cast(model.schema, obj, {
    6.       upsert: this.options && this.options.upsert,
    7.       strict: (this.options && 'strict' in this.options) ?
    8.         this.options.strict :
    9.         (model.schema.options && model.schema.options.strict),
    10.       strictQuery: (this.options && this.options.strictQuery) ||
    11.         (model.schema.options && model.schema.options.strictQuery)
    12.     }, this);
    13.   } catch (err) {
    14.     // CastError, assign model
    15.     if (typeof err.setModel === 'function') {
    16.       err.setModel(model);
    17.     }
    18.     throw err;
    19.   }
    20. };

    Query#catch([reject])

    Executes the query returning a Promise which will be
    resolved with either the doc(s) or rejected with the error.
    Like .then(), but only takes a rejection handler.

    Parameters:

    Returns:

    show code

    1. Query.prototype.catch = function(reject) {
    2.   return this.exec().then(null, reject);
    3. };

    Query#center()

    DEPRECATED Alias for circle

    Deprecated. Use circle instead.

    Query#centerSphere([path], val)

    DEPRECATED Specifies a $centerSphere condition

    Parameters:

    Returns:

    See:

    Deprecated. Use circle instead.

    Example

    1. var area = { center: [50, 50], radius: 10 };
    2. query.where('loc').within().centerSphere(area);

    show code

    1. Query.prototype.centerSphere = function() {
    2.   if (arguments[0] && arguments[0].constructor.name === 'Object') {
    3.     arguments[0].spherical = true;
    4.   }
    6.   if (arguments[1] && arguments[1].constructor.name === 'Object') {
    7.     arguments[1].spherical = true;
    8.   }
    10.   Query.base.circle.apply(this, arguments);
    11. };

    Query#circle([path], area)

    Specifies a $center or $centerSphere condition.

    Parameters:

    Returns:

    See:

    Example

    1. var area = { center: [50, 50], radius: 10, unique: true }
    2. query.where('loc').within().circle(area)
    3. // alternatively
    4. query.circle('loc', area);
    6. // spherical calculations
    7. var area = { center: [50, 50], radius: 10, unique: true, spherical: true }
    8. query.where('loc').within().circle(area)
    9. // alternatively
    10. query.circle('loc', area);

    New in 3.7.0

    Query#collation(value)

    Adds a collation to this op (MongoDB 3.4 and up)

    Parameters:

    Returns:

    See:

    show code

    1. Query.prototype.collation = function(value) {
    2.   if (this.options == null) {
    3.     this.options = {};
    4.   }
    5.   this.options.collation = value;
    6.   return this;
    7. };

    Query#comment(val)

    Specifies the comment option.

    Parameters:

    See:

    Example

    1. query.comment('login query')

    Note

    Cannot be used with distinct()

    Query#count([criteria], [callback])

    Specifying this query as a count query.

    Parameters:

    • [criteria] <Object> mongodb selector
    • [callback] <Function> optional params are (error, count)

    Returns:

    See:

    Passing a callback executes the query.

    This function triggers the following middleware

    • count()

    Example:

    1. var countQuery = model.where({ 'color': 'black' }).count();
    3. query.count({ color: 'black' }).count(callback)
    5. query.count({ color: 'black' }, callback)
    7. query.where('color', 'black').count(function (err, count) {
    8.   if (err) return handleError(err);
    9.   console.log('there are %d kittens', count);
    10. })

    show code

    1. Query.prototype.count = function(conditions, callback) {
    2.   if (typeof conditions === 'function') {
    3.     callback = conditions;
    4.     conditions = undefined;
    5.   }
    7.   if (mquery.canMerge(conditions)) {
    8.     this.merge(conditions);
    9.   }
    11.   this.op = 'count';
    12.   if (!callback) {
    13.     return this;
    14.   }
    16.   this._count(callback);
    18.   return this;
    19. };

    Query#cursor([options])

    Returns a wrapper around a mongodb driver cursor.
    A QueryCursor exposes a Streams3-compatible
    interface, as well as a .next() function.

    Parameters:

    Returns:

    See:

    The .cursor() function triggers pre find hooks, but not post find hooks.

    Example

    1. // There are 2 ways to use a cursor. First, as a stream:
    2. Thing.
    3.   find({ name: /^hello/ }).
    4.   cursor().
    5.   on('data', function(doc) { console.log(doc); }).
    6.   on('end', function() { console.log('Done!'); });
    8. // Or you can use `.next()` to manually get the next doc in the stream.
    9. // `.next()` returns a promise, so you can use promises or callbacks.
    10. var cursor = Thing.find({ name: /^hello/ }).cursor();
    11. cursor.next(function(error, doc) {
    12.   console.log(doc);
    13. });
    15. // Because `.next()` returns a promise, you can use co
    16. // to easily iterate through all documents without loading them
    17. // all into memory.
    18. co(function*() {
    19.   const cursor = Thing.find({ name: /^hello/ }).cursor();
    20.   for (let doc = yield cursor.next(); doc != null; doc = yield cursor.next()) {
    21.     console.log(doc);
    22.   }
    23. });

    Valid options

    • transform: optional function which accepts a mongoose document. The return value of the function will be emitted on data and returned by .next().

    show code

    1. Query.prototype.cursor = function cursor(opts) {
    2.   this._applyPaths();
    3.   this._fields = this._castFields(this._fields);
    4.   this.setOptions({ fields: this._fieldsForExec() });
    5.   if (opts) {
    6.     this.setOptions(opts);
    7.   }
    9.   try {
    10.     this.cast(this.model);
    11.   } catch (err) {
    12.     return (new QueryCursor(this, this.options))._markError(err);
    13.   }
    15.   return new QueryCursor(this, this.options);
    16. };
    18. // the rest of these are basically to support older Mongoose syntax with mquery

    Query#deleteMany([filter], [callback])

    Declare and/or execute this query as a deleteMany() operation. Works like
    remove, except it deletes every document that matches criteria in the
    collection, regardless of the value of single.

    Parameters:

    • [filter] <Object, Query> mongodb selector
    • [callback] <Function> optional params are (error, writeOpResult)

    Returns:

    See:

    This function does not trigger any middleware

    Example

    1. Character.deleteMany({ name: /Stark/, age: { $gte: 18 } }, callback)
    2. Character.deleteMany({ name: /Stark/, age: { $gte: 18 } }).then(next)

    show code

    1. Query.prototype.deleteMany = function(filter, callback) {
    2.   if (typeof filter === 'function') {
    3.     callback = filter;
    4.     filter = null;
    5.   }
    7.   filter = utils.toObject(filter, { retainKeyOrder: true });
    9.   try {
    10.     this.cast(this.model, filter);
    11.     this.merge(filter);
    12.   } catch (err) {
    13.     this.error(err);
    14.   }
    16.   prepareDiscriminatorCriteria(this);
    18.   if (!callback) {
    19.     return Query.base.deleteMany.call(this);
    20.   }
    22.   return this._deleteMany.call(this, callback);
    23. };

    Query#deleteOne([filter], [callback])

    Declare and/or execute this query as a deleteOne() operation. Works like
    remove, except it deletes at most one document regardless of the single
    option.

    Parameters:

    • [filter] <Object, Query> mongodb selector
    • [callback] <Function> optional params are (error, writeOpResult)

    Returns:

    See:

    This function does not trigger any middleware.

    Example

    1. Character.deleteOne({ name: 'Eddard Stark' }, callback)
    2. Character.deleteOne({ name: 'Eddard Stark' }).then(next)

    show code

    1. Query.prototype.deleteOne = function(filter, callback) {
    2.   if (typeof filter === 'function') {
    3.     callback = filter;
    4.     filter = null;
    5.   }
    7.   filter = utils.toObject(filter, { retainKeyOrder: true });
    9.   try {
    10.     this.cast(this.model, filter);
    11.     this.merge(filter);
    12.   } catch (err) {
    13.     this.error(err);
    14.   }
    16.   prepareDiscriminatorCriteria(this);
    18.   if (!callback) {
    19.     return Query.base.deleteOne.call(this);
    20.   }
    22.   return this._deleteOne.call(this, callback);
    23. };

    Query#distinct([field], [criteria], [callback])

    Declares or executes a distict() operation.

    Parameters:

    Returns:

    See:

    Passing a callback executes the query.

    This function does not trigger any middleware.

    Example

    1. distinct(field, conditions, callback)
    2. distinct(field, conditions)
    3. distinct(field, callback)
    4. distinct(field)
    5. distinct(callback)
    6. distinct()

    show code

    1. Query.prototype.distinct = function(field, conditions, callback) {
    2.   if (!callback) {
    3.     if (typeof conditions === 'function') {
    4.       callback = conditions;
    5.       conditions = undefined;
    6.     } else if (typeof field === 'function') {
    7.       callback = field;
    8.       field = undefined;
    9.       conditions = undefined;
    10.     }
    11.   }
    13.   conditions = utils.toObject(conditions);
    15.   if (mquery.canMerge(conditions)) {
    16.     this.merge(conditions);
    17.   }
    19.   try {
    20.     this.cast(this.model);
    21.   } catch (err) {
    22.     if (!callback) {
    23.       throw err;
    24.     }
    25.     callback(err);
    26.     return this;
    27.   }
    29.   return Query.base.distinct.call(this, {}, field, callback);
    30. };

    Query#elemMatch(path, criteria)

    Specifies an $elemMatch condition

    Parameters:

    Returns:

    See:

    Example

    1. query.elemMatch('comment', { author: 'autobot', votes: {$gte: 5}})
    3. query.where('comment').elemMatch({ author: 'autobot', votes: {$gte: 5}})
    5. query.elemMatch('comment', function (elem) {
    6.   elem.where('author').equals('autobot');
    7.   elem.where('votes').gte(5);
    8. })
    10. query.where('comment').elemMatch(function (elem) {
    11.   elem.where({ author: 'autobot' });
    12.   elem.where('votes').gte(5);
    13. })

    Query#equals(val)

    Specifies the complementary comparison value for paths specified with where()

    Parameters:

    Returns:

    Example

    1. User.where('age').equals(49);
    3. // is the same as
    5. User.where('age', 49);

    Query#error(err)

    Gets/sets the error flag on this query. If this flag is not null or
    undefined, the exec() promise will reject without executing.

    Parameters:

    • err <Error, null> if set, exec() will fail fast before sending the query to MongoDB

    Example:

    1. Query().error(); // Get current error value
    2. Query().error(null); // Unset the current error
    3. Query().error(new Error('test')); // `exec()` will resolve with test
    4. Schema.pre('find', function() {
    5.   if (!this.getQuery().userId) {
    6.     this.error(new Error('Not allowed to query without setting userId'));
    7.   }
    8. });

    Note that query casting runs after hooks, so cast errors will override
    custom errors.

    Example:

    1. var TestSchema = new Schema({ num: Number });
    2. var TestModel = db.model('Test', TestSchema);
    3. TestModel.find({ num: 'not a number' }).error(new Error('woops')).exec(function(error) {
    4.   // `error` will be a cast error because `num` failed to cast
    5. });

    show code

    1. Query.prototype.error = function error(err) {
    2.   if (arguments.length === 0) {
    3.     return this._error;
    4.   }
    6.   this._error = err;
    7.   return this;
    8. };

    Query#exec([operation], [callback])

    Executes the query

    Parameters:

    Returns:

    Examples:

    1. var promise = query.exec();
    2. var promise = query.exec('update');
    4. query.exec(callback);
    5. query.exec('find', callback);

    show code

    1. Query.prototype.exec = function exec(op, callback) {
    2.   var Promise = PromiseProvider.get();
    3.   var _this = this;
    5.   if (typeof op === 'function') {
    6.     callback = op;
    7.     op = null;
    8.   } else if (typeof op === 'string') {
    9.     this.op = op;
    10.   }
    12.   var _results;
    13.   var promise = new Promise.ES6(function(resolve, reject) {
    14.     if (!_this.op) {
    15.       resolve();
    16.       return;
    17.     }
    19.     _this[_this.op].call(_this, function(error, res) {
    20.       if (error) {
    21.         reject(error);
    22.         return;
    23.       }
    24.       _results = arguments;
    25.       resolve(res);
    26.     });
    27.   });
    29.   if (callback) {
    30.     promise.then(
    31.       function() {
    32.         callback.apply(null, _results);
    33.         return null;
    34.       },
    35.       function(error) {
    36.         callback(error, null);
    37.       }).
    38.       catch(function(error) {
    39.         // If we made it here, we must have an error in the callback re:
    40.         // gh-4500, so we need to emit.
    41.         setImmediate(function() {
    42.           _this.model.emit('error', error);
    43.         });
    44.       });
    45.   }
    47.   return promise;
    48. };

    Query#exists([path], val)

    Specifies an $exists condition

    Parameters:

    Returns:

    See:

    Example

    1. // { name: { $exists: true }}
    2. Thing.where('name').exists()
    3. Thing.where('name').exists(true)
    4. Thing.find().exists('name')
    6. // { name: { $exists: false }}
    7. Thing.where('name').exists(false);
    8. Thing.find().exists('name', false);

    Query#find([filter], [callback])

    Finds documents.

    Parameters:

    Returns:

    When no callback is passed, the query is not executed. When the query is executed, the result will be an array of documents.

    Example

    1. query.find({ name: 'Los Pollos Hermanos' }).find(callback)

    show code

    1. Query.prototype.find = function(conditions, callback) {
    2.   if (typeof conditions === 'function') {
    3.     callback = conditions;
    4.     conditions = {};
    5.   }
    7.   conditions = utils.toObject(conditions);
    9.   if (mquery.canMerge(conditions)) {
    10.     this.merge(conditions);
    12.     prepareDiscriminatorCriteria(this);
    13.   } else if (conditions != null) {
    14.     this.error(new ObjectParameterError(conditions, 'filter', 'find'));
    15.   }
    17.   // if we don't have a callback, then just return the query object
    18.   if (!callback) {
    19.     return Query.base.find.call(this);
    20.   }
    22.   this._find(callback);
    24.   return this;
    25. };

    Query#findOne([filter], [projection], [options], [callback])

    Declares the query a findOne operation. When executed, the first found document is passed to the callback.

    Parameters:

    Returns:

    See:

    Passing a callback executes the query. The result of the query is a single document.

    • Note: conditions is optional, and if conditions is null or undefined, mongoose will send an empty findOne command to MongoDB, which will return an arbitrary document. If you’re querying by _id, use Model.findById() instead.

    This function triggers the following middleware

    • findOne()

    Example

    1. var query  = Kitten.where({ color: 'white' });
    2. query.findOne(function (err, kitten) {
    3.   if (err) return handleError(err);
    4.   if (kitten) {
    5.     // doc may be null if no document matched
    6.   }
    7. });

    show code

    1. Query.prototype.findOne = function(conditions, projection, options, callback) {
    2.   if (typeof conditions === 'function') {
    3.     callback = conditions;
    4.     conditions = null;
    5.     projection = null;
    6.     options = null;
    7.   } else if (typeof projection === 'function') {
    8.     callback = projection;
    9.     options = null;
    10.     projection = null;
    11.   } else if (typeof options === 'function') {
    12.     callback = options;
    13.     options = null;
    14.   }
    16.   // make sure we don't send in the whole Document to merge()
    17.   conditions = utils.toObject(conditions);
    19.   this.op = 'findOne';
    21.   if (options) {
    22.     this.setOptions(options);
    23.   }
    25.   if (projection) {
    26.     this.select(projection);
    27.   }
    29.   if (mquery.canMerge(conditions)) {
    30.     this.merge(conditions);
    32.     prepareDiscriminatorCriteria(this);
    34.     try {
    35.       this.cast(this.model);
    36.       this.error(null);
    37.     } catch (err) {
    38.       this.error(err);
    39.     }
    40.   } else if (conditions != null) {
    41.     this.error(new ObjectParameterError(conditions, 'filter', 'findOne'));
    42.   }
    44.   if (!callback) {
    45.     // already merged in the conditions, don't need to send them in.
    46.     return Query.base.findOne.call(this);
    47.   }
    49.   this._findOne(callback);
    51.   return this;
    52. };

    Query#findOneAndRemove([conditions], [options], [options.passRawResult], [options.strict], [callback])

    Issues a mongodb findAndModify remove command.

    Parameters:

    Returns:

    See:

    Finds a matching document, removes it, passing the found document (if any) to the callback. Executes immediately if callback is passed.

    This function triggers the following middleware

    • findOneAndRemove()

    Available options

    Callback Signature

    1. function(error, doc, result) {
    2.   // error: any errors that occurred
    3.   // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
    4.   // result: [raw result from the MongoDB driver](http://mongodb.github.io/node-mongodb-native/2.0/api/Collection.html#findAndModify)
    5. }

    Examples

    1. A.where().findOneAndRemove(conditions, options, callback) // executes
    2. A.where().findOneAndRemove(conditions, options)  // return Query
    3. A.where().findOneAndRemove(conditions, callback) // executes
    4. A.where().findOneAndRemove(conditions) // returns Query
    5. A.where().findOneAndRemove(callback)   // executes
    6. A.where().findOneAndRemove()           // returns Query

    Query#findOneAndUpdate([query], [doc], [options], [options.passRawResult], [options.strict], [options.multipleCastError], [callback])

    Issues a mongodb findAndModify update command.

    Parameters:

    Returns:

    See:

    Finds a matching document, updates it according to the update arg, passing any options, and returns the found document (if any) to the callback. The query executes immediately if callback is passed.

    This function triggers the following middleware

    • findOneAndUpdate()

    Available options

    • new: bool - if true, return the modified document rather than the original. defaults to false (changed in 4.0)
    • upsert: bool - creates the object if it doesn’t exist. defaults to false.
    • fields: {Object|String} - Field selection. Equivalent to .select(fields).findOneAndUpdate()
    • sort: if multiple docs are found by the conditions, sets the sort order to choose which doc to update
    • maxTimeMS: puts a time limit on the query - requires mongodb >= 2.6.0
    • runValidators: if true, runs update validators on this command. Update validators validate the update operation against the model’s schema.
    • setDefaultsOnInsert: if this and upsert are true, mongoose will apply the defaults specified in the model’s schema if a new document is created. This option only works on MongoDB >= 2.4 because it relies on MongoDB’s $setOnInsert operator.
    • passRawResult: if true, passes the raw result from the MongoDB driver as the third callback parameter
    • context (string) if set to ‘query’ and runValidators is on, this will refer to the query in custom validator functions that update validation runs. Does nothing if runValidators is false.
    • runSettersOnQuery: bool - if true, run all setters defined on the associated model’s schema for all fields defined in the query and the update.

    Callback Signature

    1. function(error, doc) {
    2.   // error: any errors that occurred
    3.   // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
    4. }

    Examples

    1. query.findOneAndUpdate(conditions, update, options, callback) // executes
    2. query.findOneAndUpdate(conditions, update, options)  // returns Query
    3. query.findOneAndUpdate(conditions, update, callback) // executes
    4. query.findOneAndUpdate(conditions, update)           // returns Query
    5. query.findOneAndUpdate(update, callback)             // returns Query
    6. query.findOneAndUpdate(update)                       // returns Query
    7. query.findOneAndUpdate(callback)                     // executes
    8. query.findOneAndUpdate()                             // returns Query

    Query#geometry(object)

    Specifies a $geometry condition

    Parameters:

    • object <Object> Must contain a type property which is a String and a coordinates property which is an Array. See the examples.

    Returns:

    See:

    Example

    1. var polyA = [[[ 10, 20 ], [ 10, 40 ], [ 30, 40 ], [ 30, 20 ]]]
    2. query.where('loc').within().geometry({ type: 'Polygon', coordinates: polyA })
    4. // or
    5. var polyB = [[ 0, 0 ], [ 1, 1 ]]
    6. query.where('loc').within().geometry({ type: 'LineString', coordinates: polyB })
    8. // or
    9. var polyC = [ 0, 0 ]
    10. query.where('loc').within().geometry({ type: 'Point', coordinates: polyC })
    12. // or
    13. query.where('loc').intersects().geometry({ type: 'Point', coordinates: polyC })

    The argument is assigned to the most recent path passed to where().

    NOTE:

    geometry() must come after either intersects() or within().

    The object argument must contain type and coordinates properties.
    - type {String}
    - coordinates {Array}

    Query#getQuery()

    Returns the current query conditions as a JSON object.

    Returns:

    • <Object> current query conditions

    Example:

    1. var query = new Query();
    2. query.find({ a: 1 }).where('b').gt(2);
    3. query.getQuery(); // { a: 1, b: { $gt: 2 } }

    show code

    1. Query.prototype.getQuery = function() {
    2.   return this._conditions;
    3. };

    Query#getUpdate()

    Returns the current update operations as a JSON object.

    Returns:

    • <Object> current update operations

    Example:

    1. var query = new Query();
    2. query.update({}, { $set: { a: 5 } });
    3. query.getUpdate(); // { $set: { a: 5 } }

    show code

    1. Query.prototype.getUpdate = function() {
    2.   return this._update;
    3. };

    Query#gt([path], val)

    Specifies a $gt query condition.

    Parameters:

    See:

    When called with one argument, the most recent path passed to where() is used.

    Example

    1. Thing.find().where('age').gt(21)
    3. // or
    4. Thing.find().gt('age', 21)

    Query#gte([path], val)

    Specifies a $gte query condition.

    Parameters:

    See:

    When called with one argument, the most recent path passed to where() is used.

    Query#hint(val)

    Sets query hints.

    Parameters:

    Returns:

    See:

    Example

    1. query.hint({ indexA: 1, indexB: -1})

    Note

    Cannot be used with distinct()

    Query#in([path], val)

    Specifies an $in query condition.

    Parameters:

    See:

    When called with one argument, the most recent path passed to where() is used.

    Query#intersects([arg])

    Declares an intersects query for geometry().

    Parameters:

    Returns:

    See:

    Example

    1. query.where('path').intersects().geometry({
    2.     type: 'LineString'
    3.   , coordinates: [[180.0, 11.0], [180, 9.0]]
    4. })
    6. query.where('path').intersects({
    7.     type: 'LineString'
    8.   , coordinates: [[180.0, 11.0], [180, 9.0]]
    9. })

    NOTE:

    MUST be used after where().

    NOTE:

    In Mongoose 3.7, intersects changed from a getter to a function. If you need the old syntax, use this.

    Query#lean(bool)

    Sets the lean option.

    Parameters:

    Returns:

    Documents returned from queries with the lean option enabled are plain javascript objects, not MongooseDocuments. They have no save method, getters/setters or other Mongoose magic applied.

    Example:

    1. new Query().lean() // true
    2. new Query().lean(true)
    3. new Query().lean(false)
    5. Model.find().lean().exec(function (err, docs) {
    6.   docs[0] instanceof mongoose.Document // false
    7. });

    This is a great option in high-performance read-only scenarios, especially when combined with stream.

    show code

    1. Query.prototype.lean = function(v) {
    2.   this._mongooseOptions.lean = arguments.length ? v : true;
    3.   return this;
    4. };

    Query#limit(val)

    Specifies the maximum number of documents the query will return.

    Parameters:

    Example

    1. query.limit(20)

    Note

    Cannot be used with distinct()

    Query#lt([path], val)

    Specifies a $lt query condition.

    Parameters:

    See:

    When called with one argument, the most recent path passed to where() is used.

    Query#lte([path], val)

    Specifies a $lte query condition.

    Parameters:

    See:

    When called with one argument, the most recent path passed to where() is used.

    Query#maxDistance([path], val)

    Specifies a $maxDistance query condition.

    Parameters:

    See:

    When called with one argument, the most recent path passed to where() is used.

    Query#maxscan()

    DEPRECATED Alias of maxScan

    See:

    Query#maxScan(val)

    Specifies the maxScan option.

    Parameters:

    See:

    Example

    1. query.maxScan(100)

    Note

    Cannot be used with distinct()

    Query#merge(source)

    Merges another Query or conditions object into this one.

    Parameters:

    Returns:

    When a Query is passed, conditions, field selection and options are merged.

    show code

    1. Query.prototype.merge = function(source) {
    2.   if (!source) {
    3.     return this;
    4.   }
    6.   var opts = { retainKeyOrder: this.options.retainKeyOrder, overwrite: true };
    8.   if (source instanceof Query) {
    9.     // if source has a feature, apply it to ourselves
    11.     if (source._conditions) {
    12.       utils.merge(this._conditions, source._conditions, opts);
    13.     }
    15.     if (source._fields) {
    16.       this._fields || (this._fields = {});
    17.       utils.merge(this._fields, source._fields, opts);
    18.     }
    20.     if (source.options) {
    21.       this.options || (this.options = {});
    22.       utils.merge(this.options, source.options, opts);
    23.     }
    25.     if (source._update) {
    26.       this._update || (this._update = {});
    27.       utils.mergeClone(this._update, source._update);
    28.     }
    30.     if (source._distinct) {
    31.       this._distinct = source._distinct;
    32.     }
    34.     return this;
    35.   }
    37.   // plain object
    38.   utils.merge(this._conditions, source, opts);
    40.   return this;
    41. };

    Query#merge(source)

    Merges another Query or conditions object into this one.

    Parameters:

    Returns:

    When a Query is passed, conditions, field selection and options are merged.

    New in 3.7.0

    Query#mod([path], val)

    Specifies a $mod condition, filters documents for documents whose
    path property is a number that is equal to remainder modulo divisor.

    Parameters:

    • [path] <String>
    • val <Array> must be of length 2, first element is divisor, 2nd element is remainder.

    Returns:

    See:

    Example

    1. // All find products whose inventory is odd
    2. Product.find().mod('inventory', [2, 1]);
    3. Product.find().where('inventory').mod([2, 1]);
    4. // This syntax is a little strange, but supported.
    5. Product.find().where('inventory').mod(2, 1);

    Query#mongooseOptions(options)

    Getter/setter around the current mongoose-specific options for this query
    (populate, lean, etc.)

    Parameters:

    • options <Object> if specified, overwrites the current options

    show code

    1. Query.prototype.mongooseOptions = function(v) {
    2.   if (arguments.length > 0) {
    3.     this._mongooseOptions = v;
    4.   }
    5.   return this._mongooseOptions;
    6. };

    Query#ne([path], val)

    Specifies a $ne query condition.

    Parameters:

    See:

    When called with one argument, the most recent path passed to where() is used.

    Query#near([path], val)

    Specifies a $near or $nearSphere condition

    Parameters:

    Returns:

    See:

    These operators return documents sorted by distance.

    Example

    1. query.where('loc').near({ center: [10, 10] });
    2. query.where('loc').near({ center: [10, 10], maxDistance: 5 });
    3. query.where('loc').near({ center: [10, 10], maxDistance: 5, spherical: true });
    4. query.near('loc', { center: [10, 10], maxDistance: 5 });

    Query#nearSphere()

    DEPRECATED Specifies a $nearSphere condition

    See:

    Example

    1. query.where('loc').nearSphere({ center: [10, 10], maxDistance: 5 });

    Deprecated. Use query.near() instead with the spherical option set to true.

    Example

    1. query.where('loc').near({ center: [10, 10], spherical: true });

    show code

    1. Query.prototype.nearSphere = function() {
    2.   this._mongooseOptions.nearSphere = true;
    3.   this.near.apply(this, arguments);
    4.   return this;
    5. };

    Query#nin([path], val)

    Specifies an $nin query condition.

    Parameters:

    See:

    When called with one argument, the most recent path passed to where() is used.

    Query#nor(array)

    Specifies arguments for a $nor condition.

    Parameters:

    • array <Array> array of conditions

    Returns:

    See:

    Example

    1. query.nor([{ color: 'green' }, { status: 'ok' }])

    Query#or(array)

    Specifies arguments for an $or condition.

    Parameters:

    • array <Array> array of conditions

    Returns:

    See:

    Example

    1. query.or([{ color: 'red' }, { status: 'emergency' }])

    Query#polygon([path], [coordinatePairs...])

    Specifies a $polygon condition

    Parameters:

    Returns:

    See:

    Example

    1. query.where('loc').within().polygon([10,20], [13, 25], [7,15])
    2. query.polygon('loc', [10,20], [13, 25], [7,15])

    Query#populate(path, [select], [model], [match], [options])

    Specifies paths which should be populated with other documents.

    Parameters:

    • path <Object, String> either the path to populate or an object specifying all parameters
    • [select] <Object, String> Field selection for the population query
    • [model] <Model> The model you wish to use for population. If not specified, populate will look up the model by the name in the Schema’s ref field.
    • [match] <Object> Conditions for the population query
    • [options] <Object> Options for the population query (sort, etc)

    Returns:

    See:

    Example:

    1. Kitten.findOne().populate('owner').exec(function (err, kitten) {
    2.   console.log(kitten.owner.name) // Max
    3. })
    5. Kitten.find().populate({
    6.     path: 'owner'
    7.   , select: 'name'
    8.   , match: { color: 'black' }
    9.   , options: { sort: { name: -1 }}
    10. }).exec(function (err, kittens) {
    11.   console.log(kittens[0].owner.name) // Zoopa
    12. })
    14. // alternatively
    15. Kitten.find().populate('owner', 'name', null, {sort: { name: -1 }}).exec(function (err, kittens) {
    16.   console.log(kittens[0].owner.name) // Zoopa
    17. })

    Paths are populated after the query executes and a response is received. A separate query is then executed for each path specified for population. After a response for each query has also been returned, the results are passed to the callback.

    show code

    1. Query.prototype.populate = function() {
    2.   if (arguments.length === 0) {
    3.     return this;
    4.   }
    6.   var i;
    8.   var res = utils.populate.apply(null, arguments);
    10.   // Propagate readPreference from parent query, unless one already specified
    11.   if (this.options && this.options.readPreference != null) {
    12.     for (i = 0; i < res.length; ++i) {
    13.       if (!res[i].options || res[i].options.readPreference == null) {
    14.         res[i].options = res[i].options || {};
    15.         res[i].options.readPreference = this.options.readPreference;
    16.       }
    17.     }
    18.   }
    20.   var opts = this._mongooseOptions;
    22.   if (!utils.isObject(opts.populate)) {
    23.     opts.populate = {};
    24.   }
    26.   var pop = opts.populate;
    28.   for (i = 0; i < res.length; ++i) {
    29.     var path = res[i].path;
    30.     if (pop[path] && pop[path].populate && res[i].populate) {
    31.       res[i].populate = pop[path].populate.concat(res[i].populate);
    32.     }
    33.     pop[res[i].path] = res[i];
    34.   }
    36.   return this;
    37. };

    Query([options], [model], [conditions], [collection])

    Query constructor used for building queries.

    Parameters:

    Example:

    1. var query = new Query();
    2. query.setOptions({ lean : true });
    3. query.collection(model.collection);
    4. query.where('age').gte(21).exec(callback);

    show code

    1. function Query(conditions, options, model, collection) {
    2.   // this stuff is for dealing with custom queries created by #toConstructor
    3.   if (!this._mongooseOptions) {
    4.     this._mongooseOptions = {};
    5.   }
    7.   // this is the case where we have a CustomQuery, we need to check if we got
    8.   // options passed in, and if we did, merge them in
    9.   if (options) {
    10.     var keys = Object.keys(options);
    11.     for (var i = 0; i < keys.length; ++i) {
    12.       var k = keys[i];
    13.       this._mongooseOptions[k] = options[k];
    14.     }
    15.   }
    17.   if (collection) {
    18.     this.mongooseCollection = collection;
    19.   }
    21.   if (model) {
    22.     this.model = model;
    23.     this.schema = model.schema;
    24.   }
    26.   // this is needed because map reduce returns a model that can be queried, but
    27.   // all of the queries on said model should be lean
    28.   if (this.model && this.model._mapreduce) {
    29.     this.lean();
    30.   }
    32.   // inherit mquery
    33.   mquery.call(this, this.mongooseCollection, options);
    35.   if (conditions) {
    36.     this.find(conditions);
    37.   }
    39.   this.options = this.options || {};
    40.   if (this.schema != null && this.schema.options.collation != null) {
    41.     this.options.collation = this.schema.options.collation;
    42.   }
    44.   if (this.schema) {
    45.     var kareemOptions = {
    46.       useErrorHandlers: true,
    47.       numCallbackParams: 1,
    48.       nullResultByDefault: true
    49.     };
    50.     this._count = this.model.hooks.createWrapper('count',
    51.         Query.prototype._count, this, kareemOptions);
    52.     this._execUpdate = this.model.hooks.createWrapper('update',
    53.         Query.prototype._execUpdate, this, kareemOptions);
    54.     this._find = this.model.hooks.createWrapper('find',
    55.         Query.prototype._find, this, kareemOptions);
    56.     this._findOne = this.model.hooks.createWrapper('findOne',
    57.         Query.prototype._findOne, this, kareemOptions);
    58.     this._findOneAndRemove = this.model.hooks.createWrapper('findOneAndRemove',
    59.         Query.prototype._findOneAndRemove, this, kareemOptions);
    60.     this._findOneAndUpdate = this.model.hooks.createWrapper('findOneAndUpdate',
    61.         Query.prototype._findOneAndUpdate, this, kareemOptions);
    62.     this._replaceOne = this.model.hooks.createWrapper('replaceOne',
    63.         Query.prototype._replaceOne, this, kareemOptions);
    64.     this._updateMany = this.model.hooks.createWrapper('updateMany',
    65.         Query.prototype._updateMany, this, kareemOptions);
    66.     this._updateOne = this.model.hooks.createWrapper('updateOne',
    67.         Query.prototype._updateOne, this, kareemOptions);
    68.   }
    69. }

    Query#read(pref, [tags])

    Determines the MongoDB nodes from which to read.

    Parameters:

    • pref <String> one of the listed preference options or aliases
    • [tags] <Array> optional tags for this query

    Returns:

    See:

    Preferences:

    1. primary - (default) Read from primary only. Operations will produce an error if primary is unavailable. Cannot be combined with tags.
    2. secondary            Read from secondary if available, otherwise error.
    3. primaryPreferred     Read from primary if available, otherwise a secondary.
    4. secondaryPreferred   Read from a secondary if available, otherwise read from the primary.
    5. nearest              All operations read from among the nearest candidates, but unlike other modes, this option will include both the primary and all secondaries in the random selection.

    Aliases

    1. p   primary
    2. pp  primaryPreferred
    3. s   secondary
    4. sp  secondaryPreferred
    5. n   nearest

    Example:

    1. new Query().read('primary')
    2. new Query().read('p')  // same as primary
    4. new Query().read('primaryPreferred')
    5. new Query().read('pp') // same as primaryPreferred
    7. new Query().read('secondary')
    8. new Query().read('s')  // same as secondary
    10. new Query().read('secondaryPreferred')
    11. new Query().read('sp') // same as secondaryPreferred
    13. new Query().read('nearest')
    14. new Query().read('n')  // same as nearest
    16. // read from secondaries with matching tags
    17. new Query().read('s', [{ dc:'sf', s: 1 },{ dc:'ma', s: 2 }])

    Read more about how to use read preferrences here and here.

    Query#regex([path], val)

    Specifies a $regex query condition.

    Parameters:

    See:

    When called with one argument, the most recent path passed to where() is used.

    Query#remove([filter], [callback])

    Declare and/or execute this query as a remove() operation.

    Parameters:

    • [filter] <Object, Query> mongodb selector
    • [callback] <Function> optional params are (error, writeOpResult)

    Returns:

    See:

    This function does not trigger any middleware

    Example

    1. Model.remove({ artist: 'Anne Murray' }, callback)

    Note

    The operation is only executed when a callback is passed. To force execution without a callback, you must first call remove() and then execute it by using the exec() method.

    1. // not executed
    2. var query = Model.find().remove({ name: 'Anne Murray' })
    4. // executed
    5. query.remove({ name: 'Anne Murray' }, callback)
    6. query.remove({ name: 'Anne Murray' }).remove(callback)
    8. // executed without a callback
    9. query.exec()
    11. // summary
    12. query.remove(conds, fn); // executes
    13. query.remove(conds)
    14. query.remove(fn) // executes
    15. query.remove()

    show code

    1. Query.prototype.remove = function(filter, callback) {
    2.   if (typeof filter === 'function') {
    3.     callback = filter;
    4.     filter = null;
    5.   }
    7.   filter = utils.toObject(filter, { retainKeyOrder: true });
    9.   try {
    10.     this.cast(this.model, filter);
    11.     this.merge(filter);
    12.   } catch (err) {
    13.     this.error(err);
    14.   }
    16.   prepareDiscriminatorCriteria(this);
    18.   if (!callback) {
    19.     return Query.base.remove.call(this);
    20.   }
    22.   return this._remove(callback);
    23. };

    Query#replaceOne([criteria], [doc], [options], [callback])

    Declare and/or execute this query as a replaceOne() operation. Same as
    update(), except MongoDB will replace the existing document and will
    not accept any atomic operators ($set, etc.)

    Parameters:

    • [criteria] <Object>
    • [doc] <Object> the update command
    • [options] <Object>
    • [callback] <Function> optional params are (error, writeOpResult)

    Returns:

    See:

    Note replaceOne will not fire update middleware. Use pre('replaceOne')
    and post('replaceOne') instead.

    This function triggers the following middleware

    • replaceOne()

    show code

    1. Query.prototype.replaceOne = function(conditions, doc, options, callback) {
    2.   if (typeof options === 'function') {
    3.     // .update(conditions, doc, callback)
    4.     callback = options;
    5.     options = null;
    6.   } else if (typeof doc === 'function') {
    7.     // .update(doc, callback);
    8.     callback = doc;
    9.     doc = conditions;
    10.     conditions = {};
    11.     options = null;
    12.   } else if (typeof conditions === 'function') {
    13.     // .update(callback)
    14.     callback = conditions;
    15.     conditions = undefined;
    16.     doc = undefined;
    17.     options = undefined;
    18.   } else if (typeof conditions === 'object' && !doc && !options && !callback) {
    19.     // .update(doc)
    20.     doc = conditions;
    21.     conditions = undefined;
    22.     options = undefined;
    23.     callback = undefined;
    24.   }
    26.   this.setOptions({ overwrite: true });
    27.   return _update(this, 'replaceOne', conditions, doc, options, callback);
    28. };

    Query#select(arg)

    Specifies which document fields to include or exclude (also known as the query “projection”)

    Parameters:

    Returns:

    See:

    When using string syntax, prefixing a path with - will flag that path as excluded. When a path does not have the - prefix, it is included. Lastly, if a path is prefixed with +, it forces inclusion of the path, which is useful for paths excluded at the schema level.

    A projection must be either inclusive or exclusive. In other words, you must
    either list the fields to include (which excludes all others), or list the fields
    to exclude (which implies all other fields are included). The _id field is the only exception because MongoDB includes it by default.

    Example

    1. // include a and b, exclude other fields
    2. query.select('a b');
    4. // exclude c and d, include other fields
    5. query.select('-c -d');
    7. // or you may use object notation, useful when
    8. // you have keys already prefixed with a "-"
    9. query.select({ a: 1, b: 1 });
    10. query.select({ c: 0, d: 0 });
    12. // force inclusion of field excluded at schema level
    13. query.select('+path')

    Query#selected()

    Determines if field selection has been made.

    Returns:

    Query#selectedExclusively()

    Determines if exclusive field selection has been made.

    Returns:

    1. query.selectedExclusively() // false
    2. query.select('-name')
    3. query.selectedExclusively() // true
    4. query.selectedInclusively() // false

    Query#selectedInclusively()

    Determines if inclusive field selection has been made.

    Returns:

    1. query.selectedInclusively() // false
    2. query.select('name')
    3. query.selectedInclusively() // true

    Query#setOptions(options)

    Sets query options. Some options only make sense for certain operations.

    Parameters:

    Options:

    The following options are only for find():
    - tailable
    - sort%7D%7D)
    - limit
    - skip
    - maxscan
    - batchSize
    - comment
    - snapshot
    - readPreference
    - hint

    The following options are only for update(), updateOne(), updateMany(), replaceOne(), findOneAndUpdate(), and findByIdAndUpdate():
    - upsert
    - writeConcern

    The following options are only for find(), findOne(), findById(), findOneAndUpdate(), and findByIdAndUpdate():
    - lean

    The following options are only for all operations except update(), updateOne(), updateMany(), remove(), deleteOne(), and deleteMany():
    - maxTimeMS

    The following options are for all operations

    show code

    1. Query.prototype.setOptions = function(options, overwrite) {
    2.   // overwrite is only for internal use
    3.   if (overwrite) {
    4.     // ensure that _mongooseOptions & options are two different objects
    5.     this._mongooseOptions = (options && utils.clone(options)) || {};
    6.     this.options = options || {};
    8.     if ('populate' in options) {
    9.       this.populate(this._mongooseOptions);
    10.     }
    11.     return this;
    12.   }
    14.   if (options == null) {
    15.     return this;
    16.   }
    18.   if (Array.isArray(options.populate)) {
    19.     var populate = options.populate;
    20.     delete options.populate;
    21.     var _numPopulate = populate.length;
    22.     for (var i = 0; i < _numPopulate; ++i) {
    23.       this.populate(populate[i]);
    24.     }
    25.   }
    27.   return Query.base.setOptions.call(this, options);
    28. };

    Query#size([path], val)

    Specifies a $size query condition.

    Parameters:

    See:

    When called with one argument, the most recent path passed to where() is used.

    Example

    1. MyModel.where('tags').size(0).exec(function (err, docs) {
    2.   if (err) return handleError(err);
    4.   assert(Array.isArray(docs));
    5.   console.log('documents with 0 tags', docs);
    6. })

    Query#skip(val)

    Specifies the number of documents to skip.

    Parameters:

    See:

    Example

    1. query.skip(100).limit(20)

    Note

    Cannot be used with distinct()

    Query#slaveOk(v)

    DEPRECATED Sets the slaveOk option.

    Parameters:

    Returns:

    See:

    Deprecated in MongoDB 2.2 in favor of read preferences.

    Example:

    1. query.slaveOk() // true
    2. query.slaveOk(true)
    3. query.slaveOk(false)

    Query#slice([path], val)

    Specifies a $slice projection for an array.

    Parameters:

    • [path] <String>
    • val <Number> number/range of elements to slice

    Returns:

    See:

    Example

    1. query.slice('comments', 5)
    2. query.slice('comments', -5)
    3. query.slice('comments', [10, 5])
    4. query.where('comments').slice(5)
    5. query.where('comments').slice([-10, 5])

    Query#slice([path], [val])

    Specifies a path for use with chaining.

    Parameters:

    Returns:

    Example

    1. // instead of writing:
    2. User.find({age: {$gte: 21, $lte: 65}}, callback);
    4. // we can instead write:
    5. User.where('age').gte(21).lte(65);
    7. // passing query conditions is permitted
    8. User.find().where({ name: 'vonderful' })
    10. // chaining
    11. User
    12. .where('age').gte(21).lte(65)
    13. .where('name', /^vonderful/i)
    14. .where('friends').slice(10)
    15. .exec(callback)

    Query#snapshot()

    Specifies this query as a snapshot query.

    Returns:

    See:

    Example

    1. query.snapshot() // true
    2. query.snapshot(true)
    3. query.snapshot(false)

    Note

    Cannot be used with distinct()

    Query#sort(arg)

    Sets the sort order

    Parameters:

    Returns:

    See:

    If an object is passed, values allowed are asc, desc, ascending, descending, 1, and -1.

    If a string is passed, it must be a space delimited list of path names. The
    sort order of each path is ascending unless the path name is prefixed with -
    which will be treated as descending.

    Example

    1. // sort by "field" ascending and "test" descending
    2. query.sort({ field: 'asc', test: -1 });
    4. // equivalent
    5. query.sort('field -test');

    Note

    Cannot be used with distinct()

    show code

    1. Query.prototype.sort = function(arg) {
    2.   if (arguments.length > 1) {
    3.     throw new Error('sort() only takes 1 Argument');
    4.   }
    6.   return Query.base.sort.call(this, arg);
    7. };

    Query#stream([options])

    Returns a Node.js 0.8 style read stream interface.

    Parameters:

    Returns:

    See:

    Example

    1. // follows the nodejs 0.8 stream api
    2. Thing.find({ name: /^hello/ }).stream().pipe(res)
    4. // manual streaming
    5. var stream = Thing.find({ name: /^hello/ }).stream();
    7. stream.on('data', function (doc) {
    8.   // do something with the mongoose document
    9. }).on('error', function (err) {
    10.   // handle the error
    11. }).on('close', function () {
    12.   // the stream is closed
    13. });

    Valid options

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

    Example

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

    show code

    1. Query.prototype.stream = function stream(opts) {
    2.   this._applyPaths();
    3.   this._fields = this._castFields(this._fields);
    4.   this._castConditions();
    5.   return new QueryStream(this, opts);
    6. };
    7. Query.prototype.stream = util.deprecate(Query.prototype.stream, 'Mongoose: ' +
    8.   'Query.prototype.stream() is deprecated in mongoose >= 4.5.0, ' +
    9.   'use Query.prototype.cursor() instead');

    Query#tailable(bool, [opts], [opts.numberOfRetries], [opts.tailableRetryInterval])

    Sets the tailable option (for use with capped collections).

    Parameters:

    • bool <Boolean> defaults to true
    • [opts] <Object> options to set
    • [opts.numberOfRetries] <Number> if cursor is exhausted, retry this many times before giving up
    • [opts.tailableRetryInterval] <Number> if cursor is exhausted, wait this many milliseconds before retrying

    See:

    Example

    1. query.tailable() // true
    2. query.tailable(true)
    3. query.tailable(false)

    Note

    Cannot be used with distinct()

    show code

    1. Query.prototype.tailable = function(val, opts) {
    2.   // we need to support the tailable({ awaitdata : true }) as well as the
    3.   // tailable(true, {awaitdata :true}) syntax that mquery does not support
    4.   if (val && val.constructor.name === 'Object') {
    5.     opts = val;
    6.     val = true;
    7.   }
    9.   if (val === undefined) {
    10.     val = true;
    11.   }
    13.   if (opts && typeof opts === 'object') {
    14.     for (var key in opts) {
    15.       if (key === 'awaitdata') {
    16.         // For backwards compatibility
    17.         this.options[key] = !!opts[key];
    18.       } else {
    19.         this.options[key] = opts[key];
    20.       }
    21.     }
    22.   }
    24.   return Query.base.tailable.call(this, val);
    25. };

    Query#then([resolve], [reject])

    Executes the query returning a Promise which will be
    resolved with either the doc(s) or rejected with the error.

    Parameters:

    Returns:

    show code

    1. Query.prototype.then = function(resolve, reject) {
    2.   return this.exec().then(resolve, reject);
    3. };

    Query#toConstructor()

    Converts this query to a customized, reusable query constructor with all arguments and options retained.

    Returns:

    • <Query> subclass-of-Query

    Example

    1. // Create a query for adventure movies and read from the primary
    2. // node in the replica-set unless it is down, in which case we'll
    3. // read from a secondary node.
    4. var query = Movie.find({ tags: 'adventure' }).read('primaryPreferred');
    6. // create a custom Query constructor based off these settings
    7. var Adventure = query.toConstructor();
    9. // Adventure is now a subclass of mongoose.Query and works the same way but with the
    10. // default query parameters and options set.
    11. Adventure().exec(callback)
    13. // further narrow down our query results while still using the previous settings
    14. Adventure().where({ name: /^Life/ }).exec(callback);
    16. // since Adventure is a stand-alone constructor we can also add our own
    17. // helper methods and getters without impacting global queries
    18. Adventure.prototype.startsWith = function (prefix) {
    19.   this.where({ name: new RegExp('^' + prefix) })
    20.   return this;
    21. }
    22. Object.defineProperty(Adventure.prototype, 'highlyRated', {
    23.   get: function () {
    24.     this.where({ rating: { $gt: 4.5 }});
    25.     return this;
    26.   }
    27. })
    28. Adventure().highlyRated.startsWith('Life').exec(callback)

    New in 3.7.3

    show code

    1. Query.prototype.toConstructor = function toConstructor() {
    2.   var model = this.model;
    3.   var coll = this.mongooseCollection;
    5.   var CustomQuery = function(criteria, options) {
    6.     if (!(this instanceof CustomQuery)) {
    7.       return new CustomQuery(criteria, options);
    8.     }
    9.     this._mongooseOptions = utils.clone(p._mongooseOptions);
    10.     Query.call(this, criteria, options || null, model, coll);
    11.   };
    13.   util.inherits(CustomQuery, Query);
    15.   // set inherited defaults
    16.   var p = CustomQuery.prototype;
    18.   p.options = {};
    20.   p.setOptions(this.options);
    22.   p.op = this.op;
    23.   p._conditions = utils.clone(this._conditions, { retainKeyOrder: true });
    24.   p._fields = utils.clone(this._fields);
    25.   p._update = utils.clone(this._update, {
    26.     flattenDecimals: false,
    27.     retainKeyOrder: true
    28.   });
    29.   p._path = this._path;
    30.   p._distinct = this._distinct;
    31.   p._collection = this._collection;
    32.   p._mongooseOptions = this._mongooseOptions;
    34.   return CustomQuery;
    35. };

    Query#update([criteria], [doc], [options], [options.multipleCastError], [callback])

    Declare and/or execute this query as an update() operation.

    Parameters:

    • [criteria] <Object>
    • [doc] <Object> the update command
    • [options] <Object>
    • [options.multipleCastError] <Boolean> by default, mongoose only returns the first error that occurred in casting the query. Turn on this option to aggregate all the cast errors.
    • [callback] <Function> optional, params are (error, writeOpResult)

    Returns:

    See:

    All paths passed that are not $atomic operations will become $set ops.

    This function triggers the following middleware

    • update()

    Example

    1. Model.where({ _id: id }).update({ title: 'words' })
    3. // becomes
    5. Model.where({ _id: id }).update({ $set: { title: 'words' }})

    Valid options:

    • safe (boolean) safe mode (defaults to value set in schema (true))
    • upsert (boolean) whether to create the doc if it doesn’t match (false)
    • multi (boolean) whether multiple documents should be updated (false)
    • runValidators: if true, runs update validators on this command. Update validators validate the update operation against the model’s schema.
    • setDefaultsOnInsert: if this and upsert are true, mongoose will apply the defaults specified in the model’s schema if a new document is created. This option only works on MongoDB >= 2.4 because it relies on MongoDB’s $setOnInsert operator.
    • strict (boolean) overrides the strict option for this update
    • overwrite (boolean) disables update-only mode, allowing you to overwrite the doc (false)
    • context (string) if set to ‘query’ and runValidators is on, this will refer to the query in custom validator functions that update validation runs. Does nothing if runValidators is false.

    Note

    Passing an empty object {} as the doc will result in a no-op unless the overwrite option is passed. Without the overwrite option set, the update operation will be ignored and the callback executed without sending the command to MongoDB so as to prevent accidently overwritting documents in the collection.

    Note

    The operation is only executed when a callback is passed. To force execution without a callback, we must first call update() and then execute it by using the exec() method.

    1. var q = Model.where({ _id: id });
    2. q.update({ $set: { name: 'bob' }}).update(); // not executed
    4. q.update({ $set: { name: 'bob' }}).exec(); // executed
    6. // keys that are not $atomic ops become $set.
    7. // this executes the same command as the previous example.
    8. q.update({ name: 'bob' }).exec();
    10. // overwriting with empty docs
    11. var q = Model.where({ _id: id }).setOptions({ overwrite: true })
    12. q.update({ }, callback); // executes
    14. // multi update with overwrite to empty doc
    15. var q = Model.where({ _id: id });
    16. q.setOptions({ multi: true, overwrite: true })
    17. q.update({ });
    18. q.update(callback); // executed
    20. // multi updates
    21. Model.where()
    22.      .update({ name: /^match/ }, { $set: { arr: [] }}, { multi: true }, callback)
    24. // more multi updates
    25. Model.where()
    26.      .setOptions({ multi: true })
    27.      .update({ $set: { arr: [] }}, callback)
    29. // single update by default
    30. Model.where({ email: 'address@example.com' })
    31.      .update({ $inc: { counter: 1 }}, callback)

    API summary

    1. update(criteria, doc, options, cb) // executes
    2. update(criteria, doc, options)
    3. update(criteria, doc, cb) // executes
    4. update(criteria, doc)
    5. update(doc, cb) // executes
    6. update(doc)
    7. update(cb) // executes
    8. update(true) // executes
    9. update()

    show code

    1. Query.prototype.update = function(conditions, doc, options, callback) {
    2.   if (typeof options === 'function') {
    3.     // .update(conditions, doc, callback)
    4.     callback = options;
    5.     options = null;
    6.   } else if (typeof doc === 'function') {
    7.     // .update(doc, callback);
    8.     callback = doc;
    9.     doc = conditions;
    10.     conditions = {};
    11.     options = null;
    12.   } else if (typeof conditions === 'function') {
    13.     // .update(callback)
    14.     callback = conditions;
    15.     conditions = undefined;
    16.     doc = undefined;
    17.     options = undefined;
    18.   } else if (typeof conditions === 'object' && !doc && !options && !callback) {
    19.     // .update(doc)
    20.     doc = conditions;
    21.     conditions = undefined;
    22.     options = undefined;
    23.     callback = undefined;
    24.   }
    26.   return _update(this, 'update', conditions, doc, options, callback);
    27. };

    Query#updateMany([criteria], [doc], [options], [callback])

    Declare and/or execute this query as an updateMany() operation. Same as
    update(), except MongoDB will update all documents that match
    criteria (as opposed to just the first one) regardless of the value of
    the multi option.

    Parameters:

    • [criteria] <Object>
    • [doc] <Object> the update command
    • [options] <Object>
    • [callback] <Function> optional params are (error, writeOpResult)

    Returns:

    See:

    Note updateMany will not fire update middleware. Use pre('updateMany')
    and post('updateMany') instead.

    This function triggers the following middleware

    • updateMany()

    show code

    1. Query.prototype.updateMany = function(conditions, doc, options, callback) {
    2.   if (typeof options === 'function') {
    3.     // .update(conditions, doc, callback)
    4.     callback = options;
    5.     options = null;
    6.   } else if (typeof doc === 'function') {
    7.     // .update(doc, callback);
    8.     callback = doc;
    9.     doc = conditions;
    10.     conditions = {};
    11.     options = null;
    12.   } else if (typeof conditions === 'function') {
    13.     // .update(callback)
    14.     callback = conditions;
    15.     conditions = undefined;
    16.     doc = undefined;
    17.     options = undefined;
    18.   } else if (typeof conditions === 'object' && !doc && !options && !callback) {
    19.     // .update(doc)
    20.     doc = conditions;
    21.     conditions = undefined;
    22.     options = undefined;
    23.     callback = undefined;
    24.   }
    26.   return _update(this, 'updateMany', conditions, doc, options, callback);
    27. };

    Query#updateOne([criteria], [doc], [options], [callback])

    Declare and/or execute this query as an updateOne() operation. Same as
    update(), except MongoDB will update only the first document that
    matches criteria regardless of the value of the multi option.

    Parameters:

    Returns:

    See:

    Note updateOne will not fire update middleware. Use pre('updateOne')
    and post('updateOne') instead.

    This function triggers the following middleware

    • updateOne()

    show code

    1. Query.prototype.updateOne = function(conditions, doc, options, callback) {
    2.   if (typeof options === 'function') {
    3.     // .update(conditions, doc, callback)
    4.     callback = options;
    5.     options = null;
    6.   } else if (typeof doc === 'function') {
    7.     // .update(doc, callback);
    8.     callback = doc;
    9.     doc = conditions;
    10.     conditions = {};
    11.     options = null;
    12.   } else if (typeof conditions === 'function') {
    13.     // .update(callback)
    14.     callback = conditions;
    15.     conditions = undefined;
    16.     doc = undefined;
    17.     options = undefined;
    18.   } else if (typeof conditions === 'object' && !doc && !options && !callback) {
    19.     // .update(doc)
    20.     doc = conditions;
    21.     conditions = undefined;
    22.     options = undefined;
    23.     callback = undefined;
    24.   }
    26.   return _update(this, 'updateOne', conditions, doc, options, callback);
    27. };

    Query#within()

    Defines a $within or $geoWithin argument for geo-spatial queries.

    Returns:

    See:

    Example

    1. query.where(path).within().box()
    2. query.where(path).within().circle()
    3. query.where(path).within().geometry()
    5. query.where('loc').within({ center: [50,50], radius: 10, unique: true, spherical: true });
    6. query.where('loc').within({ box: [[40.73, -73.9], [40.7, -73.988]] });
    7. query.where('loc').within({ polygon: [[],[],[],[]] });
    9. query.where('loc').within([], [], []) // polygon
    10. query.where('loc').within([], []) // box
    11. query.where('loc').within({ type: 'LineString', coordinates: [...] }); // geometry

    MUST be used after where().

    NOTE:

    As of Mongoose 3.7, $geoWithin is always used for queries. To change this behavior, see Query.use$geoWithin.

    NOTE:

    In Mongoose 3.7, within changed from a getter to a function. If you need the old syntax, use this.

    Query._ensurePath(method)

    Makes sure _path is set.

    Parameters:

    Query._fieldsForExec()

    Returns fields selection for this query.

    Returns:

    Query._updateForExec()

    Return an update document with corrected $set operations.

    Query#use$geoWithin

    Flag to opt out of using $geoWithin.

    1. mongoose.Query.use$geoWithin = false;

    MongoDB 2.4 deprecated the use of $within, replacing it with $geoWithin. Mongoose uses $geoWithin by default (which is 100% backward compatible with $within). If you are running an older version of MongoDB, set this flag to false so your within() queries continue to work.

    show code

    1. Query.use$geoWithin = mquery.use$geoWithin;

    See:

  • promise_provider.js

    ()

    Helper for multiplexing promise implementations

    show code

    1. var Promise = {
    2.   _promise: MPromise
    3. };

    Promise.get()

    Get the current promise constructor

    show code

    1. Promise.get = function() {
    2.   return Promise._promise;
    3. };

    Promise.reset()

    Resets to using mpromise

    show code

    1. Promise.reset = function() {
    2.   Promise._promise = MPromise;
    3. };
    5. module.exports = Promise;

    Promise.set()

    Set the current promise constructor

    show code

    1. Promise.set = function(lib) {
    2.   if (lib === MPromise) {
    3.     return Promise.reset();
    4.   }
    5.   Promise._promise = require('./ES6Promise');
    6.   Promise._promise.use(lib);
    7.   require('mquery').Promise = Promise._promise.ES6;
    8. };

  • schema.js

    Schema#add(obj, prefix)

    Adds key path / schema type pairs to this schema.

    Parameters:

    Example:

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

    show code

    1. Schema.prototype.add = function add(obj, prefix) {
    2.   prefix = prefix || '';
    3.   var keys = Object.keys(obj);
    5.   for (var i = 0; i < keys.length; ++i) {
    6.     var key = keys[i];
    8.     if (obj[key] == null) {
    9.       throw new TypeError('Invalid value for schema path `' + prefix + key + '`');
    10.     }
    12.     if (Array.isArray(obj[key]) && obj[key].length === 1 && obj[key][0] == null) {
    13.       throw new TypeError('Invalid value for schema Array path `' + prefix + key + '`');
    14.     }
    16.     if (utils.isObject(obj[key]) &&
    17.         (!obj[key].constructor || utils.getFunctionName(obj[key].constructor) === 'Object') &&
    18.         (!obj[key][this.options.typeKey] || (this.options.typeKey === 'type' && obj[key].type.type))) {
    19.       if (Object.keys(obj[key]).length) {
    20.         // nested object { last: { name: String }}
    21.         this.nested[prefix + key] = true;
    22.         this.add(obj[key], prefix + key + '.');
    23.       } else {
    24.         if (prefix) {
    25.           this.nested[prefix.substr(0, prefix.length - 1)] = true;
    26.         }
    27.         this.path(prefix + key, obj[key]); // mixed type
    28.       }
    29.     } else {
    30.       if (prefix) {
    31.         this.nested[prefix.substr(0, prefix.length - 1)] = true;
    32.       }
    33.       this.path(prefix + key, obj[key]);
    34.     }
    35.   }
    36. };

    Schema#clone()

    Returns a deep copy of the schema

    Returns:

    show code

    1. Schema.prototype.clone = function() {
    2.   var s = new Schema(this.paths, this.options);
    3.   // Clone the call queue
    4.   var cloneOpts = { retainKeyOrder: true };
    5.   s.callQueue = this.callQueue.map(function(f) { return f; });
    6.   s.methods = utils.clone(this.methods, cloneOpts);
    7.   s.statics = utils.clone(this.statics, cloneOpts);
    8.   s.query = utils.clone(this.query, cloneOpts);
    9.   s.plugins = Array.prototype.slice.call(this.plugins);
    10.   s._indexes = utils.clone(this._indexes, cloneOpts);
    11.   s.s.hooks = this.s.hooks.clone();
    12.   return s;
    13. };

    Schema#defaultOptions(options)

    Returns default options for this schema, merged with options.

    Parameters:

    Returns:

    show code

    1. Schema.prototype.defaultOptions = function(options) {
    2.   if (options && options.safe === false) {
    3.     options.safe = {w: 0};
    4.   }
    6.   if (options && options.safe && options.safe.w === 0) {
    7.     // if you turn off safe writes, then versioning goes off as well
    8.     options.versionKey = false;
    9.   }
    11.   this._userProvidedOptions = utils.clone(options, {
    12.     retainKeyOrder: true
    13.   });
    15.   options = utils.options({
    16.     strict: true,
    17.     bufferCommands: true,
    18.     capped: false, // { size, max, autoIndexId }
    19.     versionKey: '__v',
    20.     discriminatorKey: '__t',
    21.     minimize: true,
    22.     autoIndex: null,
    23.     shardKey: null,
    24.     read: null,
    25.     validateBeforeSave: true,
    26.     // the following are only applied at construction time
    27.     noId: false, // deprecated, use { _id: false }
    28.     _id: true,
    29.     noVirtualId: false, // deprecated, use { id: false }
    30.     id: true,
    31.     typeKey: 'type',
    32.     retainKeyOrder: false
    33.   }, options);
    35.   if (options.read) {
    36.     options.read = readPref(options.read);
    37.   }
    39.   return options;
    40. };

    Schema#eachPath(fn)

    Iterates the schemas paths similar to Array#forEach.

    Parameters:

    Returns:

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

    show code

    1. Schema.prototype.eachPath = function(fn) {
    2.   var keys = Object.keys(this.paths),
    3.       len = keys.length;
    5.   for (var i = 0; i < len; ++i) {
    6.     fn(keys[i], this.paths[keys[i]]);
    7.   }
    9.   return this;
    10. };

    Schema#get(key)

    Gets a schema option.

    Parameters:

    show code

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

    Schema#hasMixedParent(path)

    Returns true iff this path is a child of a mixed schema.

    Parameters:

    Returns:

    show code

    1. Schema.prototype.hasMixedParent = function(path) {
    2.   var subpaths = path.split(/\./g);
    3.   path = '';
    4.   for (var i = 0; i < subpaths.length; ++i) {
    5.     path = i > 0 ? path + '.' + subpaths[i] : subpaths[i];
    6.     if (path in this.paths &&
    7.         this.paths[path] instanceof MongooseTypes.Mixed) {
    8.       return true;
    9.     }
    10.   }
    12.   return false;
    13. };

    Schema#index(fields, [options], [options.expires=null])

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

    Parameters:

    Example

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

    show code

    1. Schema.prototype.index = function(fields, options) {
    2.   options || (options = {});
    4.   if (options.expires) {
    5.     utils.expires(options);
    6.   }
    8.   this._indexes.push([fields, options]);
    9.   return this;
    10. };

    Schema#indexedPaths()

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

    Returns:

    show code

    1. Schema.prototype.indexedPaths = function indexedPaths() {
    2.   if (this._indexedpaths) {
    3.     return this._indexedpaths;
    4.   }
    5.   this._indexedpaths = this.indexes();
    6.   return this._indexedpaths;
    7. };

    Schema#indexes()

    Returns a list of indexes that this schema declares, via schema.index()
    or by index: true in a path’s options.

    show code

    1. Schema.prototype.indexes = function() {
    2.   'use strict';
    4.   var indexes = [];
    5.   var schemaStack = [];
    7.   var collectIndexes = function(schema, prefix) {
    8.     // Ignore infinitely nested schemas, if we've already seen this schema
    9.     // along this path there must be a cycle
    10.     if (schemaStack.indexOf(schema) !== -1) {
    11.       return;
    12.     }
    13.     schemaStack.push(schema);
    15.     prefix = prefix || '';
    16.     var key, path, index, field, isObject, options, type;
    17.     var keys = Object.keys(schema.paths);
    19.     for (var i = 0; i < keys.length; ++i) {
    20.       key = keys[i];
    21.       path = schema.paths[key];
    23.       if ((path instanceof MongooseTypes.DocumentArray) || path.$isSingleNested) {
    24.         if (path.options.excludeIndexes !== true) {
    25.           collectIndexes(path.schema, prefix + key + '.');
    26.         }
    27.       } else {
    28.         index = path._index || (path.caster && path.caster._index);
    30.         if (index !== false && index !== null && index !== undefined) {
    31.           field = {};
    32.           isObject = utils.isObject(index);
    33.           options = isObject ? index : {};
    34.           type = typeof index === 'string' ? index :
    35.               isObject ? index.type :
    36.                   false;
    38.           if (type && ~Schema.indexTypes.indexOf(type)) {
    39.             field[prefix + key] = type;
    40.           } else if (options.text) {
    41.             field[prefix + key] = 'text';
    42.             delete options.text;
    43.           } else {
    44.             field[prefix + key] = 1;
    45.           }
    47.           delete options.type;
    48.           if (!('background' in options)) {
    49.             options.background = true;
    50.           }
    52.           indexes.push([field, options]);
    53.         }
    54.       }
    55.     }
    57.     schemaStack.pop();
    59.     if (prefix) {
    60.       fixSubIndexPaths(schema, prefix);
    61.     } else {
    62.       schema._indexes.forEach(function(index) {
    63.         if (!('background' in index[1])) {
    64.           index[1].background = true;
    65.         }
    66.       });
    67.       indexes = indexes.concat(schema._indexes);
    68.     }
    69.   };
    71.   collectIndexes(this);
    72.   return indexes;

    Schema#loadClass(model)

    Loads an ES6 class into a schema. Maps setters + getters, static methods, and instance methods to schema virtuals, statics, and methods.

    Parameters:

    show code

    1. Schema.prototype.loadClass = function(model, virtualsOnly) {
    2.   if (model === Object.prototype ||
    3.       model === Function.prototype ||
    4.       model.prototype.hasOwnProperty('$isMongooseModelPrototype')) {
    5.     return this;
    6.   }
    8.   this.loadClass(Object.getPrototypeOf(model));
    10.   // Add static methods
    11.   if (!virtualsOnly) {
    12.     Object.getOwnPropertyNames(model).forEach(function(name) {
    13.       if (name.match(/^(length|name|prototype)$/)) {
    14.         return;
    15.       }
    16.       var method = Object.getOwnPropertyDescriptor(model, name);
    17.       if (typeof method.value === 'function') {
    18.         this.static(name, method.value);
    19.       }
    20.     }, this);
    21.   }
    23.   // Add methods and virtuals
    24.   Object.getOwnPropertyNames(model.prototype).forEach(function(name) {
    25.     if (name.match(/^(constructor)$/)) {
    26.       return;
    27.     }
    28.     var method = Object.getOwnPropertyDescriptor(model.prototype, name);
    29.     if (!virtualsOnly) {
    30.       if (typeof method.value === 'function') {
    31.         this.method(name, method.value);
    32.       }
    33.     }
    34.     if (typeof method.get === 'function') {
    35.       this.virtual(name).get(method.get);
    36.     }
    37.     if (typeof method.set === 'function') {
    38.       this.virtual(name).set(method.set);
    39.     }
    40.   }, this);
    42.   return this;
    43. };

    Schema#method(method, [fn])

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

    Parameters:

    Example

    1. var schema = kittySchema = new Schema(..);
    3. schema.method('meow', function () {
    4.   console.log('meeeeeoooooooooooow');
    5. })
    7. var Kitty = mongoose.model('Kitty', schema);
    9. var fizz = new Kitty;
    10. 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.

    1. schema.method({
    2.     purr: function () {}
    3.   , scratch: function () {}
    4. });
    6. // later
    7. fizz.purr();
    8. fizz.scratch();

    show code

    1. Schema.prototype.method = function(name, fn) {
    2.   if (typeof name !== 'string') {
    3.     for (var i in name) {
    4.       this.methods[i] = name[i];
    5.     }
    6.   } else {
    7.     this.methods[name] = fn;
    8.   }
    9.   return this;
    10. };

    Schema#path(path, constructor)

    Gets/sets schema paths.

    Parameters:

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

    Example

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

    show code

    1. Schema.prototype.path = function(path, obj) {
    2.   if (obj === undefined) {
    3.     if (this.paths[path]) {
    4.       return this.paths[path];
    5.     }
    6.     if (this.subpaths[path]) {
    7.       return this.subpaths[path];
    8.     }
    9.     if (this.singleNestedPaths[path]) {
    10.       return this.singleNestedPaths[path];
    11.     }
    13.     // subpaths?
    14.     return /\.\d+\.?.*$/.test(path)
    15.         ? getPositionalPath(this, path)
    16.         : undefined;
    17.   }
    19.   // some path names conflict with document methods
    20.   if (reserved[path]) {
    21.     throw new Error('`' + path + '` may not be used as a schema pathname');
    22.   }
    24.   if (warnings[path]) {
    25.     console.log('WARN: ' + warnings[path]);
    26.   }
    28.   // update the tree
    29.   var subpaths = path.split(/\./),
    30.       last = subpaths.pop(),
    31.       branch = this.tree;
    33.   subpaths.forEach(function(sub, i) {
    34.     if (!branch[sub]) {
    35.       branch[sub] = {};
    36.     }
    37.     if (typeof branch[sub] !== 'object') {
    38.       var msg = 'Cannot set nested path `' + path + '`. '
    39.           + 'Parent path `'
    40.           + subpaths.slice(0, i).concat([sub]).join('.')
    41.           + '` already set to type ' + branch[sub].name
    42.           + '.';
    43.       throw new Error(msg);
    44.     }
    45.     branch = branch[sub];
    46.   });
    48.   branch[last] = utils.clone(obj);
    50.   this.paths[path] = Schema.interpretAsType(path, obj, this.options);
    52.   if (this.paths[path].$isSingleNested) {
    53.     for (var key in this.paths[path].schema.paths) {
    54.       this.singleNestedPaths[path + '.' + key] =
    55.           this.paths[path].schema.paths[key];
    56.     }
    57.     for (key in this.paths[path].schema.singleNestedPaths) {
    58.       this.singleNestedPaths[path + '.' + key] =
    59.           this.paths[path].schema.singleNestedPaths[key];
    60.     }
    62.     this.childSchemas.push({
    63.       schema: this.paths[path].schema,
    64.       model: this.paths[path].caster
    65.     });
    66.   } else if (this.paths[path].$isMongooseDocumentArray) {
    67.     this.childSchemas.push({
    68.       schema: this.paths[path].schema,
    69.       model: this.paths[path].casterConstructor
    70.     });
    71.   }
    72.   return this;
    73. };

    Schema#pathType(path)

    Returns the pathType of path for this schema.

    Parameters:

    Returns:

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

    show code

    1. Schema.prototype.pathType = function(path) {
    2.   if (path in this.paths) {
    3.     return 'real';
    4.   }
    5.   if (path in this.virtuals) {
    6.     return 'virtual';
    7.   }
    8.   if (path in this.nested) {
    9.     return 'nested';
    10.   }
    11.   if (path in this.subpaths) {
    12.     return 'real';
    13.   }
    14.   if (path in this.singleNestedPaths) {
    15.     return 'real';
    16.   }
    18.   if (/\.\d+\.|\.\d+$/.test(path)) {
    19.     return getPositionalPathType(this, path);
    20.   }
    21.   return 'adhocOrUndefined';
    22. };

    Schema#plugin(plugin, [opts])

    Registers a plugin for this schema.

    Parameters:

    See:

    show code

    1. Schema.prototype.plugin = function(fn, opts) {
    2.   if (typeof fn !== 'function') {
    3.     throw new Error('First param to `schema.plugin()` must be a function, ' +
    4.       'got "' + (typeof fn) + '"');
    5.   }
    7.   if (opts &&
    8.       opts.deduplicate) {
    9.     for (var i = 0; i < this.plugins.length; ++i) {
    10.       if (this.plugins[i].fn === fn) {
    11.         return this;
    12.       }
    13.     }
    14.   }
    15.   this.plugins.push({ fn: fn, opts: opts });
    17.   fn(this, opts);
    18.   return this;
    19. };

    Schema#post(method, fn)

    Defines a post hook for the document

    Parameters:

    See:

    1. var schema = new Schema(..);
    2. schema.post('save', function (doc) {
    3.   console.log('this fired after a document was saved');
    4. });
    6. schema.post('find', function(docs) {
    7.   console.log('this fired after you run a find query');
    8. });
    10. var Model = mongoose.model('Model', schema);
    12. var m = new Model(..);
    13. m.save(function(err) {
    14.   console.log('this fires after the `post` hook');
    15. });
    17. m.find(function(err, docs) {
    18.   console.log('this fires after the post find hook');
    19. });

    show code

    1. Schema.prototype.post = function(method, fn) {
    2.   if (IS_KAREEM_HOOK[method]) {
    3.     this.s.hooks.post.apply(this.s.hooks, arguments);
    4.     return this;
    5.   }
    6.   // assuming that all callbacks with arity < 2 are synchronous post hooks
    7.   if (fn.length < 2) {
    8.     return this.queue('on', [arguments[0], function(doc) {
    9.       return fn.call(doc, doc);
    10.     }]);
    11.   }
    13.   if (fn.length === 3) {
    14.     this.s.hooks.post(method + ':error', fn);
    15.     return this;
    16.   }
    18.   return this.queue('post', [arguments[0], function(next) {
    19.     // wrap original function so that the callback goes last,
    20.     // for compatibility with old code that is using synchronous post hooks
    21.     var _this = this;
    22.     var args = Array.prototype.slice.call(arguments, 1);
    23.     fn.call(this, this, function(err) {
    24.       return next.apply(_this, [err].concat(args));
    25.     });
    26.   }]);
    27. };

    Schema#pre(method, callback)

    Defines a pre hook for the document.

    Parameters:

    See:

    Example

    1. var toySchema = new Schema(..);
    3. toySchema.pre('save', function (next) {
    4.   if (!this.created) this.created = new Date;
    5.   next();
    6. })
    8. toySchema.pre('validate', function (next) {
    9.   if (this.name !== 'Woody') this.name = 'Woody';
    10.   next();
    11. })

    show code

    1. Schema.prototype.pre = function() {
    2.   var name = arguments[0];
    3.   if (IS_KAREEM_HOOK[name]) {
    4.     this.s.hooks.pre.apply(this.s.hooks, arguments);
    5.     return this;
    6.   }
    7.   return this.queue('pre', arguments);
    8. };

    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

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

    Schema#remove(path)

    Removes the given path (or [paths]).

    Parameters:

    show code

    1. Schema.prototype.remove = function(path) {
    2.   if (typeof path === 'string') {
    3.     path = [path];
    4.   }
    5.   if (Array.isArray(path)) {
    6.     path.forEach(function(name) {
    7.       if (this.path(name)) {
    8.         delete this.paths[name];
    10.         var pieces = name.split('.');
    11.         var last = pieces.pop();
    12.         var branch = this.tree;
    13.         for (var i = 0; i < pieces.length; ++i) {
    14.           branch = branch[pieces[i]];
    15.         }
    16.         delete branch[last];
    17.       }
    18.     }, this);
    19.   }
    20. };

    Schema#requiredPaths(invalidate)

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

    Parameters:

    • invalidate <Boolean> refresh the cache

    Returns:

    show code

    1. Schema.prototype.requiredPaths = function requiredPaths(invalidate) {
    2.   if (this._requiredpaths && !invalidate) {
    3.     return this._requiredpaths;
    4.   }
    6.   var paths = Object.keys(this.paths),
    7.       i = paths.length,
    8.       ret = [];
    10.   while (i--) {
    11.     var path = paths[i];
    12.     if (this.paths[path].isRequired) {
    13.       ret.push(path);
    14.     }
    15.   }
    16.   this._requiredpaths = ret;
    17.   return this._requiredpaths;
    18. };

    Schema(definition, [options])

    Schema constructor.

    Parameters:

    Inherits:

    Events:

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

    Example:

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

    Options:

    Note:

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

    show code

    1. function Schema(obj, options) {
    2.   if (!(this instanceof Schema)) {
    3.     return new Schema(obj, options);
    4.   }
    6.   this.obj = obj;
    7.   this.paths = {};
    8.   this.aliases = {};
    9.   this.subpaths = {};
    10.   this.virtuals = {};
    11.   this.singleNestedPaths = {};
    12.   this.nested = {};
    13.   this.inherits = {};
    14.   this.callQueue = [];
    15.   this._indexes = [];
    16.   this.methods = {};
    17.   this.statics = {};
    18.   this.tree = {};
    19.   this.query = {};
    20.   this.childSchemas = [];
    21.   this.plugins = [];
    23.   this.s = {
    24.     hooks: new Kareem(),
    25.     kareemHooks: IS_KAREEM_HOOK
    26.   };
    28.   this.options = this.defaultOptions(options);
    30.   // build paths
    31.   if (obj) {
    32.     this.add(obj);
    33.   }
    35.   // check if _id's value is a subdocument (gh-2276)
    36.   var _idSubDoc = obj && obj._id && utils.isObject(obj._id);
    38.   // ensure the documents get an auto _id unless disabled
    39.   var auto_id = !this.paths['_id'] &&
    40.       (!this.options.noId && this.options._id) && !_idSubDoc;
    42.   if (auto_id) {
    43.     var _obj = {_id: {auto: true}};
    44.     _obj._id[this.options.typeKey] = Schema.ObjectId;
    45.     this.add(_obj);
    46.   }
    48.   for (var i = 0; i < this._defaultMiddleware.length; ++i) {
    49.     var m = this._defaultMiddleware[i];
    50.     this[m.kind](m.hook, !!m.isAsync, m.fn);
    51.   }
    53.   if (this.options.timestamps) {
    54.     this.setupTimestamp(this.options.timestamps);
    55.   }
    57.   // Assign virtual properties based on alias option
    58.   aliasFields(this);
    59. }

    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

    See:

    Example

    1. schema.set('strict'); // 'true' by default
    2. schema.set('strict', false); // Sets 'strict' to false
    3. schema.set('strict'); // 'false'

    show code

    1. Schema.prototype.set = function(key, value, _tags) {
    2.   if (arguments.length === 1) {
    3.     return this.options[key];
    4.   }
    6.   switch (key) {
    7.     case 'read':
    8.       this.options[key] = readPref(value, _tags);
    9.       break;
    10.     case 'safe':
    11.       this.options[key] = value === false
    12.           ? {w: 0}
    13.           : value;
    14.       break;
    15.     case 'timestamps':
    16.       this.setupTimestamp(value);
    17.       this.options[key] = value;
    18.       break;
    19.     default:
    20.       this.options[key] = value;
    21.   }
    23.   return this;
    24. };

    Schema#setupTimestamp(timestamps)

    Setup updatedAt and createdAt timestamps to documents if enabled

    Parameters:

    show code

    1. Schema.prototype.setupTimestamp = function(timestamps) {
    2.   if (timestamps) {
    3.     var createdAt = handleTimestampOption(timestamps, 'createdAt');
    4.     var updatedAt = handleTimestampOption(timestamps, 'updatedAt');
    5.     var schemaAdditions = {};
    7.     if (updatedAt && !this.paths[updatedAt]) {
    8.       schemaAdditions[updatedAt] = Date;
    9.     }
    11.     if (createdAt && !this.paths[createdAt]) {
    12.       schemaAdditions[createdAt] = Date;
    13.     }
    15.     this.add(schemaAdditions);
    17.     this.pre('save', function(next) {
    18.       var defaultTimestamp = new Date();
    19.       var auto_id = this._id && this._id.auto;
    21.       if (createdAt != null && !this.get(createdAt) && this.isSelected(createdAt)) {
    22.         this.set(createdAt, auto_id ? this._id.getTimestamp() : defaultTimestamp);
    23.       }
    25.       if (updatedAt != null && (this.isNew || this.isModified())) {
    26.         var ts = defaultTimestamp;
    27.         if (this.isNew) {
    28.           if (createdAt != null) {
    29.             ts = this.get(createdAt);
    30.           } else if (auto_id) {
    31.             ts = this._id.getTimestamp();
    32.           }
    33.         }
    34.         this.set(updatedAt, ts);
    35.       }
    37.       next();
    38.     });
    40.     var genUpdates = function(currentUpdate, overwrite) {
    41.       var now = new Date();
    42.       var updates = {};
    43.       var _updates = updates;
    44.       if (overwrite) {
    45.         if (currentUpdate && currentUpdate.$set) {
    46.           currentUpdate = currentUpdate.$set;
    47.           updates.$set = {};
    48.           _updates = updates.$set;
    49.         }
    50.         if (updatedAt != null && !currentUpdate[updatedAt]) {
    51.           _updates[updatedAt] = now;
    52.         }
    53.         if (createdAt != null && !currentUpdate[createdAt]) {
    54.           _updates[createdAt] = now;
    55.         }
    56.         return updates;
    57.       }
    58.       updates = { $set: {} };
    59.       currentUpdate = currentUpdate || {};
    61.       if (updatedAt != null &&
    62.           (!currentUpdate.$currentDate || !currentUpdate.$currentDate[updatedAt])) {
    63.         updates.$set[updatedAt] = now;
    64.       }
    66.       if (createdAt != null) {
    67.         if (currentUpdate[createdAt]) {
    68.           delete currentUpdate[createdAt];
    69.         }
    70.         if (currentUpdate.$set && currentUpdate.$set[createdAt]) {
    71.           delete currentUpdate.$set[createdAt];
    72.         }
    74.         updates.$setOnInsert = {};
    75.         updates.$setOnInsert[createdAt] = now;
    76.       }
    78.       return updates;
    79.     };
    81.     this.methods.initializeTimestamps = function() {
    82.       if (!this.get(createdAt)) {
    83.         this.set(createdAt, new Date());
    84.       }
    85.       if (!this.get(updatedAt)) {
    86.         this.set(updatedAt, new Date());
    87.       }
    88.       return this;
    89.     };
    91.     this.pre('findOneAndUpdate', function(next) {
    92.       var overwrite = this.options.overwrite;
    93.       this.findOneAndUpdate({}, genUpdates(this.getUpdate(), overwrite), {
    94.         overwrite: overwrite
    95.       });
    96.       applyTimestampsToChildren(this);
    97.       next();
    98.     });
    100.     this.pre('update', function(next) {
    101.       var overwrite = this.options.overwrite;
    102.       this.update({}, genUpdates(this.getUpdate(), overwrite), {
    103.         overwrite: overwrite
    104.       });
    105.       applyTimestampsToChildren(this);
    106.       next();
    107.     });
    108.   }
    109. };

    Schema#static(name, [fn])

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

    Parameters:

    Example

    1. var schema = new Schema(..);
    2. schema.static('findByName', function (name, callback) {
    3.   return this.find({ name: name }, callback);
    4. });
    6. var Drink = mongoose.model('Drink', schema);
    7. Drink.findByName('sanpellegrino', function (err, drinks) {
    8.   //
    9. });

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

    show code

    1. Schema.prototype.static = function(name, fn) {
    2.   if (typeof name !== 'string') {
    3.     for (var i in name) {
    4.       this.statics[i] = name[i];
    5.     }
    6.   } else {
    7.     this.statics[name] = fn;
    8.   }
    9.   return this;
    10. };

    Schema#virtual(name, [options])

    Creates a virtual type with the given name.

    Parameters:

    Returns:

    show code

    1. Schema.prototype.virtual = function(name, options) {
    2.   if (options && options.ref) {
    3.     if (!options.localField) {
    4.       throw new Error('Reference virtuals require `localField` option');
    5.     }
    7.     if (!options.foreignField) {
    8.       throw new Error('Reference virtuals require `foreignField` option');
    9.     }
    11.     this.pre('init', function(next, obj) {
    12.       if (mpath.has(name, obj)) {
    13.         var _v = mpath.get(name, obj);
    14.         if (!this.$$populatedVirtuals) {
    15.           this.$$populatedVirtuals = {};
    16.         }
    18.         if (options.justOne) {
    19.           this.$$populatedVirtuals[name] = Array.isArray(_v) ?
    20.             _v[0] :
    21.             _v;
    22.         } else {
    23.           this.$$populatedVirtuals[name] = Array.isArray(_v) ?
    24.             _v :
    25.             _v == null ? [] : [_v];
    26.         }
    28.         mpath.unset(name, obj);
    29.       }
    30.       if (this.ownerDocument) {
    31.         next();
    32.         return this;
    33.       } else {
    34.         next();
    35.       }
    36.     });
    38.     var virtual = this.virtual(name);
    39.     virtual.options = options;
    40.     return virtual.
    41.       get(function() {
    42.         if (!this.$$populatedVirtuals) {
    43.           this.$$populatedVirtuals = {};
    44.         }
    45.         if (name in this.$$populatedVirtuals) {
    46.           return this.$$populatedVirtuals[name];
    47.         }
    48.         return null;
    49.       }).
    50.       set(function(_v) {
    51.         if (!this.$$populatedVirtuals) {
    52.           this.$$populatedVirtuals = {};
    53.         }
    55.         if (options.justOne) {
    56.           this.$$populatedVirtuals[name] = Array.isArray(_v) ?
    57.             _v[0] :
    58.             _v;
    60.           if (typeof this.$$populatedVirtuals[name] !== 'object') {
    61.             this.$$populatedVirtuals[name] = null;
    62.           }
    63.         } else {
    64.           this.$$populatedVirtuals[name] = Array.isArray(_v) ?
    65.             _v :
    66.             _v == null ? [] : [_v];
    68.           this.$$populatedVirtuals[name] = this.$$populatedVirtuals[name].filter(function(doc) {
    69.             return doc && typeof doc === 'object';
    70.           });
    71.         }
    72.       });
    73.   }
    75.   var virtuals = this.virtuals;
    76.   var parts = name.split('.');
    78.   if (this.pathType(name) === 'real') {
    79.     throw new Error('Virtual path "' + name + '"' +
    80.       ' conflicts with a real path in the schema');
    81.   }
    83.   virtuals[name] = parts.reduce(function(mem, part, i) {
    84.     mem[part] || (mem[part] = (i === parts.length - 1)
    85.         ? new VirtualType(options, name)
    86.         : {});
    87.     return mem[part];
    88.   }, this.tree);
    90.   return virtuals[name];
    91. };

    Schema#virtualpath(name)

    Returns the virtual type with the given name.

    Parameters:

    Returns:

    show code

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

    Schema.indexTypes()

    The allowed index types

    show code

    1. var indexTypes = '2d 2dsphere hashed text'.split(' ');
    3. Object.defineProperty(Schema, 'indexTypes', {
    4.   get: function() {
    5.     return indexTypes;
    6.   },
    7.   set: function() {
    8.     throw new Error('Cannot overwrite Schema.indexTypes');
    9.   }
    10. });

    Schema.interpretAsType(path, obj)

    Converts type arguments into Mongoose Types.

    show code

    1. Schema.interpretAsType = function(path, obj, options) {
    2.   if (obj instanceof SchemaType) {
    3.     return obj;
    4.   }
    6.   if (obj.constructor) {
    7.     var constructorName = utils.getFunctionName(obj.constructor);
    8.     if (constructorName !== 'Object') {
    9.       var oldObj = obj;
    10.       obj = {};
    11.       obj[options.typeKey] = oldObj;
    12.     }
    13.   }
    15.   // Get the type making sure to allow keys named "type"
    16.   // and default to mixed if not specified.
    17.   // { type: { type: String, default: 'freshcut' } }
    18.   var type = obj[options.typeKey] && (options.typeKey !== 'type' || !obj.type.type)
    19.       ? obj[options.typeKey]
    20.       : {};
    22.   if (utils.getFunctionName(type.constructor) === 'Object' || type === 'mixed') {
    23.     return new MongooseTypes.Mixed(path, obj);
    24.   }
    26.   if (Array.isArray(type) || Array === type || type === 'array') {
    27.     // if it was specified through { type } look for `cast`
    28.     var cast = (Array === type || type === 'array')
    29.         ? obj.cast
    30.         : type[0];
    32.     if (cast && cast.instanceOfSchema) {
    33.       return new MongooseTypes.DocumentArray(path, cast, obj);
    34.     }
    35.     if (cast &&
    36.         cast[options.typeKey] &&
    37.         cast[options.typeKey].instanceOfSchema) {
    38.       return new MongooseTypes.DocumentArray(path, cast[options.typeKey], cast);
    39.     }
    41.     if (Array.isArray(cast)) {
    42.       return new MongooseTypes.Array(path, Schema.interpretAsType(path, cast, options), obj);
    43.     }
    45.     if (typeof cast === 'string') {
    46.       cast = MongooseTypes[cast.charAt(0).toUpperCase() + cast.substring(1)];
    47.     } else if (cast && (!cast[options.typeKey] || (options.typeKey === 'type' && cast.type.type))
    48.         && utils.getFunctionName(cast.constructor) === 'Object') {
    49.       if (Object.keys(cast).length) {
    50.         // The `minimize` and `typeKey` options propagate to child schemas
    51.         // declared inline, like `{ arr: [{ val: { $type: String } }] }`.
    52.         // See gh-3560
    53.         var childSchemaOptions = {minimize: options.minimize};
    54.         if (options.typeKey) {
    55.           childSchemaOptions.typeKey = options.typeKey;
    56.         }
    57.         //propagate 'strict' option to child schema
    58.         if (options.hasOwnProperty('strict')) {
    59.           childSchemaOptions.strict = options.strict;
    60.         }
    61.         //propagate 'runSettersOnQuery' option to child schema
    62.         if (options.hasOwnProperty('runSettersOnQuery')) {
    63.           childSchemaOptions.runSettersOnQuery = options.runSettersOnQuery;
    64.         }
    65.         var childSchema = new Schema(cast, childSchemaOptions);
    66.         childSchema.$implicitlyCreated = true;
    67.         return new MongooseTypes.DocumentArray(path, childSchema, obj);
    68.       } else {
    69.         // Special case: empty object becomes mixed
    70.         return new MongooseTypes.Array(path, MongooseTypes.Mixed, obj);
    71.       }
    72.     }
    74.     if (cast) {
    75.       type = cast[options.typeKey] && (options.typeKey !== 'type' || !cast.type.type)
    76.           ? cast[options.typeKey]
    77.           : cast;
    79.       name = typeof type === 'string'
    80.           ? type
    81.           : type.schemaName || utils.getFunctionName(type);
    83.       if (!(name in MongooseTypes)) {
    84.         throw new TypeError('Undefined type `' + name + '` at array `' + path +
    85.           '`');
    86.       }
    87.     }
    89.     return new MongooseTypes.Array(path, cast || MongooseTypes.Mixed, obj, options);
    90.   }
    92.   if (type && type.instanceOfSchema) {
    93.     return new MongooseTypes.Embedded(type, path, obj);
    94.   }
    96.   var name;
    97.   if (Buffer.isBuffer(type)) {
    98.     name = 'Buffer';
    99.   } else {
    100.     name = typeof type === 'string'
    101.         ? type
    102.       // If not string, `type` is a function. Outside of IE, function.name
    103.       // gives you the function name. In IE, you need to compute it
    104.         : type.schemaName || utils.getFunctionName(type);
    105.   }
    107.   if (name) {
    108.     name = name.charAt(0).toUpperCase() + name.substring(1);
    109.   }
    111.   if (undefined == MongooseTypes[name]) {
    112.     throw new TypeError('Undefined type `' + name + '` at `' + path +
    113.         '`
    114.   Did you try nesting Schemas? ' +
    115.         'You can only nest using refs or arrays.');
    116.   }
    118.   obj = utils.clone(obj, { retainKeyOrder: true });
    119.   if (!('runSettersOnQuery' in obj)) {
    120.     obj.runSettersOnQuery = options.runSettersOnQuery;
    121.   }
    122.   return new MongooseTypes[name](path, obj);
    123. };

    Parameters:

    Schema.reserved

    Reserved document keys.

    show code

    1. Schema.reserved = Object.create(null);
    2. var reserved = Schema.reserved;
    3. // Core object
    4. reserved['prototype'] =
    5. // EventEmitter
    6. reserved.emit =
    7. reserved.on =
    8. reserved.once =
    9. reserved.listeners =
    10. reserved.removeListener =
    11. // document properties and functions
    12. reserved.collection =
    13. reserved.db =
    14. reserved.errors =
    15. reserved.init =
    16. reserved.isModified =
    17. reserved.isNew =
    18. reserved.get =
    19. reserved.modelName =
    20. reserved.save =
    21. reserved.schema =
    22. reserved.toObject =
    23. reserved.validate =
    24. reserved.remove =
    25. // hooks.js
    26. reserved._pres = reserved._posts = 1;

    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.

    1. 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.

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

    Schema.Types

    The various built-in Mongoose Schema Types.

    show code

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

    Example:

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

    Types:

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

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

    Schema#_defaultMiddleware

    Default middleware attached to a schema. Cannot be changed.

    This field is used to make sure discriminators don’t get multiple copies of
    built-in middleware. Declared as a constant because changing this at runtime
    may lead to instability with Model.prototype.discriminator().

    show code

    1. Object.defineProperty(Schema.prototype, '_defaultMiddleware', {
    2.   configurable: false,
    3.   enumerable: false,
    4.   writable: false,
    5.   value: [
    6.     {
    7.       kind: 'pre',
    8.       hook: 'remove',
    9.       isAsync: true,
    10.       fn: function(next, done) {
    11.         if (this.ownerDocument) {
    12.           done();
    13.           next();
    14.           return;
    15.         }
    17.         var subdocs = this.$__getAllSubdocs();
    19.         if (!subdocs.length) {
    20.           done();
    21.           next();
    22.           return;
    23.         }
    25.         each(subdocs, function(subdoc, cb) {
    26.           subdoc.remove({ noop: true }, function(err) {
    27.             cb(err);
    28.           });
    29.         }, function(error) {
    30.           if (error) {
    31.             done(error);
    32.             return;
    33.           }
    34.           next();
    35.           done();
    36.         });
    37.       }
    38.     }
    39.   ]
    40. });

    Schema#childSchemas

    Array of child schemas (from document arrays and single nested subdocs)
    and their corresponding compiled models. Each element of the array is
    an object with 2 properties: schema and model.

    This property is typically only useful for plugin authors and advanced users.
    You do not need to interact with this property at all to use mongoose.

    show code

    1. Object.defineProperty(Schema.prototype, 'childSchemas', {
    2.   configurable: false,
    3.   enumerable: true,
    4.   writable: true
    5. });

    Schema#obj

    The original object passed to the schema constructor

    Example:

    1. var schema = new Schema({ a: String }).add({ b: String });
    2. schema.obj; // { a: String }

    show code

    1. Schema.prototype.obj;

    Schema#paths

    Schema as flat paths

    Example:

    1. {
    2.     '_id'        : SchemaType,
    3.   , 'nested.key' : SchemaType,
    4. }

    show code

    1. Schema.prototype.paths;

    Schema#tree

    Schema as a tree

    Example:

    1. {
    2.     '_id'     : ObjectId
    3.   , 'nested'  : {
    4.         'key' : String
    5.     }
    6. }

    show code

    1. Schema.prototype.tree;

  • document_provider.web.js

    module.exports()

    Returns the Document constructor for the current context

    show code

    1. module.exports = function() {
    2.   return BrowserDocument;
    3. };

  • collection.js

    Collection#addQueue(name, args)

    Queues a method for later execution when its
    database connection opens.

    Parameters:

    • name <String> name of the method to queue
    • args <Array> arguments to pass to the method when executed

    show code

    1. Collection.prototype.addQueue = function(name, args) {
    2.   this.queue.push([name, args]);
    3.   return this;
    4. };

    Collection(name, conn, opts)

    Abstract Collection constructor

    Parameters:

    • name <String> name of the collection
    • conn <Connection> A MongooseConnection instance
    • opts <Object> optional collection options

    This is the base class that drivers inherit from and implement.

    show code

    1. function Collection(name, conn, opts) {
    2.   if (opts === void 0) {
    3.     opts = {};
    4.   }
    5.   if (opts.capped === void 0) {
    6.     opts.capped = {};
    7.   }
    9.   opts.bufferCommands = undefined === opts.bufferCommands
    10.       ? true
    11.       : opts.bufferCommands;
    13.   if (typeof opts.capped === 'number') {
    14.     opts.capped = {size: opts.capped};
    15.   }
    17.   this.opts = opts;
    18.   this.name = name;
    19.   this.collectionName = name;
    20.   this.conn = conn;
    21.   this.queue = [];
    22.   this.buffer = this.opts.bufferCommands;
    23.   this.emitter = new EventEmitter();
    25.   if (STATES.connected === this.conn.readyState) {
    26.     this.onOpen();
    27.   }
    28. }

    Collection#createIndex()

    Abstract method that drivers must implement.

    show code

    1. Collection.prototype.createIndex = function() {
    2.   throw new Error('Collection#ensureIndex unimplemented by driver');
    3. };

    Collection#doQueue()

    Executes all queued methods and clears the queue.

    show code

    1. Collection.prototype.doQueue = function() {
    2.   for (var i = 0, l = this.queue.length; i < l; i++) {
    3.     if (typeof this.queue[i][0] === 'function') {
    4.       this.queue[i][0].apply(this, this.queue[i][1]);
    5.     } else {
    6.       this[this.queue[i][0]].apply(this, this.queue[i][1]);
    7.     }
    8.   }
    9.   this.queue = [];
    10.   var _this = this;
    11.   process.nextTick(function() {
    12.     _this.emitter.emit('queue');
    13.   });
    14.   return this;
    15. };

    Collection#ensureIndex()

    Abstract method that drivers must implement.

    show code

    1. Collection.prototype.ensureIndex = function() {
    2.   throw new Error('Collection#ensureIndex unimplemented by driver');
    3. };

    Collection#find()

    Abstract method that drivers must implement.

    show code

    1. Collection.prototype.find = function() {
    2.   throw new Error('Collection#find unimplemented by driver');
    3. };

    Collection#findAndModify()

    Abstract method that drivers must implement.

    show code

    1. Collection.prototype.findAndModify = function() {
    2.   throw new Error('Collection#findAndModify unimplemented by driver');
    3. };

    Collection#findOne()

    Abstract method that drivers must implement.

    show code

    1. Collection.prototype.findOne = function() {
    2.   throw new Error('Collection#findOne unimplemented by driver');
    3. };

    Collection#getIndexes()

    Abstract method that drivers must implement.

    show code

    1. Collection.prototype.getIndexes = function() {
    2.   throw new Error('Collection#getIndexes unimplemented by driver');
    3. };

    Collection#insert()

    Abstract method that drivers must implement.

    show code

    1. Collection.prototype.insert = function() {
    2.   throw new Error('Collection#insert unimplemented by driver');
    3. };

    Collection#mapReduce()

    Abstract method that drivers must implement.

    show code

    1. Collection.prototype.mapReduce = function() {
    2.   throw new Error('Collection#mapReduce unimplemented by driver');
    3. };

    Collection#onClose()

    Called when the database disconnects

    show code

    1. Collection.prototype.onClose = function(force) {
    2.   if (this.opts.bufferCommands && !force) {
    3.     this.buffer = true;
    4.   }
    5. };

    Collection#onOpen()

    Called when the database connects

    show code

    1. Collection.prototype.onOpen = function() {
    2.   this.buffer = false;
    3.   var _this = this;
    4.   setImmediate(function() {
    5.     _this.doQueue();
    6.   });
    7. };

    Collection#save()

    Abstract method that drivers must implement.

    show code

    1. Collection.prototype.save = function() {
    2.   throw new Error('Collection#save unimplemented by driver');
    3. };

    Collection#update()

    Abstract method that drivers must implement.

    show code

    1. Collection.prototype.update = function() {
    2.   throw new Error('Collection#update unimplemented by driver');
    3. };

    Collection#collectionName

    The collection name

    show code

    1. Collection.prototype.collectionName;

    Collection#conn

    The Connection instance

    show code

    1. Collection.prototype.conn;

    Collection#name

    The collection name

    show code

    1. Collection.prototype.name;