- index.js
Mongoose#Mongoose()
The Mongoose constructor
The exports of the mongoose module is an instance of this class.
Example:
var mongoose = require('mongoose'); var mongoose2 = new mongoose.Mongoose();
Mongoose()
Mongoose constructor.
show codeThe exports object of the
mongoose
module is an instance of this class.
Most apps will only use this one instance.function Mongoose () { this.connections = []; this.plugins = []; this.models = {}; this.modelSchemas = {}; // default global options this.options = { pluralization: true }; this.createConnection(); // default connection };
Mongoose#Schema()
The Mongoose Schema constructor
Example:
var mongoose = require('mongoose'); var Schema = mongoose.Schema; var CatSchema = new Schema(..);
Mongoose#_applyPlugins(
schema
)Applies global plugins to
schema
.show codeParameters:
schema
<Schema>
Mongoose.prototype._applyPlugins = function (schema) { for (var i = 0, l = this.plugins.length; i < l; i++) { schema.plugin(this.plugins[i][0], this.plugins[i][1]); } }
Mongoose#connect(
uri(s)
,[options]
,[callback]
)Opens the default mongoose connection.
Returns:
- <Mongoose> this
show codeIf arguments are passed, they are proxied to either Connection#open or Connection#openSet appropriately.
Options passed take precedence over options included in connection strings.
Example:
mongoose.connect('mongodb://user:pass@localhost:port/database'); // replica sets var uri = 'mongodb://user:pass@localhost:port/database,mongodb://anotherhost:port,mongodb://yetanother:port'; mongoose.connect(uri); // with options mongoose.connect(uri, options); // connecting to multiple mongos var uri = 'mongodb://hostA:27501,hostB:27501'; var opts = { mongos: true }; mongoose.connect(uri, opts);
Mongoose.prototype.connect = function () { var conn = this.connection; if (rgxReplSet.test(arguments[0])) { conn.openSet.apply(conn, arguments); } else { conn.open.apply(conn, arguments); } return this; };
Mongoose#createConnection(
[uri]
,[options]
)Creates a Connection instance.
Returns:
- <Connection> the created Connection object
show codeEach
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
, andreplset
options to the driver. Note that thesafe
option specified in your schema will overwrite thesafe
db option specified here unless you set your schemassafe
option toundefined
. See this for more information.Options passed take precedence over options included in connection strings.
Example:
// with mongodb:// URI db = mongoose.createConnection('mongodb://user:pass@localhost:port/database'); // and options var opts = { db: { native_parser: true }} db = mongoose.createConnection('mongodb://user:pass@localhost:port/database', opts); // replica sets db = mongoose.createConnection('mongodb://user:pass@localhost:port/database,mongodb://anotherhost:port,mongodb://yetanother:port'); // and options var opts = { replset: { strategy: 'ping', rs_name: 'testSet' }} db = mongoose.createConnection('mongodb://user:pass@localhost:port/database,mongodb://anotherhost:port,mongodb://yetanother:port', opts); // with [host, database_name[, port] signature db = mongoose.createConnection('localhost', 'database', port) // and options var opts = { server: { auto_reconnect: false }, user: 'username', pass: 'mypassword' } db = mongoose.createConnection('localhost', 'database', port, opts) // initialize now, connect later db = mongoose.createConnection(); db.open('localhost', 'database', port, [opts]);
Mongoose.prototype.createConnection = function () { var conn = new Connection(this); this.connections.push(conn); if (arguments.length) { if (rgxReplSet.test(arguments[0])) { conn.openSet.apply(conn, arguments); } else { conn.open.apply(conn, arguments); } } return conn; };
Mongoose#disconnect(
[fn]
)Disconnects all connections.
Parameters:
[fn]
<Function> called after all connection close.
show codeReturns:
- <Mongoose> this
Mongoose.prototype.disconnect = function (fn) { var count = this.connections.length , error this.connections.forEach(function(conn){ conn.close(function(err){ if (error) return; if (err) { error = err; if (fn) return fn(err); throw err; } if (fn) --count || fn(); }); }); return this; };
Mongoose#get(
key
)Gets mongoose options
Parameters:
key
<String>
Example:
mongoose.get('test') // returns the 'test' value
Mongoose#model(
name
,[schema]
,[collection]
,[skipInit]
)Defines a model or retrieves it.
Parameters:
show codeModels defined on the
mongoose
instance are available to all connection created by the samemongoose
instance.Example:
var mongoose = require('mongoose'); // define an Actor model with this mongoose instance mongoose.model('Actor', new Schema({ name: String })); // create a new connection var conn = mongoose.createConnection(..); // retrieve the Actor model var Actor = conn.model('Actor');
When no
collection
argument is passed, Mongoose produces a collection name by passing the modelname
to the utils.toCollectionName method. This method pluralizes the name. If you don't like this behavior, either pass a collection name or set your schemas collection name option.Example:
var schema = new Schema({ name: String }, { collection: 'actor' }); // or schema.set('collection', 'actor'); // or var collectionName = 'actor' var M = mongoose.model('Actor', schema, collectionName)
Mongoose.prototype.model = function (name, schema, collection, skipInit) { if ('string' == typeof schema) { collection = schema; schema = false; } if (utils.isObject(schema) && !(schema instanceof Schema)) { schema = new Schema(schema); } if ('boolean' === typeof collection) { skipInit = collection; collection = null; } // handle internal options from connection.model() var options; if (skipInit && utils.isObject(skipInit)) { options = skipInit; skipInit = true; } else { options = {}; } // look up schema for the collection. this might be a // default schema like system.indexes stored in SchemaDefaults. if (!this.modelSchemas[name]) { if (!schema && name in SchemaDefaults) { schema = SchemaDefaults[name]; } if (schema) { // cache it so we only apply plugins once this.modelSchemas[name] = schema; this._applyPlugins(schema); } else { throw new mongoose.Error.MissingSchemaError(name); } } var model; var sub; // connection.model() may be passing a different schema for // an existing model name. in this case don't read from cache. if (this.models[name] && false !== options.cache) { if (schema instanceof Schema && schema != this.models[name].schema) { throw new mongoose.Error.OverwriteModelError(name); } if (collection) { // subclass current model with alternate collection model = this.models[name]; schema = model.prototype.schema; sub = model.__subclass(this.connection, schema, collection); // do not cache the sub model return sub; } return this.models[name]; } // ensure a schema exists if (!schema) { schema = this.modelSchemas[name]; if (!schema) { throw new mongoose.Error.MissingSchemaError(name); } } // Apply relevant "global" options to the schema if (!('pluralization' in schema.options)) schema.options.pluralization = this.options.pluralization; if (!collection) { collection = schema.get('collection') || format(name, schema.options); } var connection = options.connection || this.connection; model = Model.compile(name, schema, collection, connection, this); if (!skipInit) { model.init(); } if (false === options.cache) { return model; } return this.models[name] = model; }
Mongoose#modelNames()
Returns an array of model names created on this instance of Mongoose.
Returns:
- <Array>
show codeNote:
Does not include names of models created using
connection.model()
.Mongoose.prototype.modelNames = function () { var names = Object.keys(this.models); return names; }
Mongoose#plugin(
fn
,[opts]
)Declares a global plugin executed on all Schemas.
Returns:
- <Mongoose> this
See:
show codeEquivalent to calling
.plugin(fn)
on each Schema you create.Mongoose.prototype.plugin = function (fn, opts) { this.plugins.push([fn, opts]); return this; };
Mongoose#set(
key
,value
)Sets mongoose options
show codeExample:
mongoose.set('test', value) // sets the 'test' option to `value` mongoose.set('debug', true) // enable logging collection methods + arguments to the console
Mongoose.prototype.set = function (key, value) { if (arguments.length == 1) { return this.options[key]; } this.options[key] = value; return this; };
Mongoose#SchemaTypes
The various Mongoose SchemaTypes.
Note:
Alias of mongoose.Schema.Types for backwards compatibility.
show codeMongoose.prototype.SchemaTypes = Schema.Types;
Mongoose#Types
The various Mongoose Types.
Example:
var mongoose = require('mongoose'); var array = mongoose.Types.Array;
Types:
Using this exposed access to the
ObjectId
type, we can construct ids on demand.
show codevar ObjectId = mongoose.Types.ObjectId; var id1 = new ObjectId;
Mongoose.prototype.Types = Types;
Mongoose#connection
The default connection of the mongoose module.
Example:
var mongoose = require('mongoose'); mongoose.connect(...); mongoose.connection.on('error', cb);
This is the connection used by default for every model created using mongoose.model.
show codeMongoose.prototype.__defineGetter__('connection', function(){ return this.connections[0]; });
Returns:
Mongoose#mongo
The node-mongodb-native driver Mongoose uses.
show codeMongoose.prototype.mongo = require('mongodb');
Mongoose#mquery
The mquery query builder Mongoose uses.
show codeMongoose.prototype.mquery = require('mquery');
- aggregate.js
Aggregate(
[ops]
)Aggregate constructor used for building aggregation pipelines.
show codeExample:
new Aggregate(); new Aggregate({ $project: { a: 1, b: 1 } }); new Aggregate({ $project: { a: 1, b: 1 } }, { $skip: 5 }); new Aggregate([{ $project: { a: 1, b: 1 } }, { $skip: 5 }]);
Returned when calling Model.aggregate().
Example:
Model .aggregate({ $match: { age: { $gte: 21 }}}) .unwind('tags') .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
function Aggregate () { this._pipeline = []; this._model = undefined; this.options = undefined; if (1 === arguments.length && util.isArray(arguments[0])) { this.append.apply(this, arguments[0]); } else { this.append.apply(this, arguments); } }
Aggregate#append(
ops
)Appends new operators to this aggregate pipeline
Parameters:
ops
<Object> operator(s) to append
Returns:
show codeExamples:
aggregate.append({ $project: { field: 1 }}, { $limit: 2 }); // or pass an array var pipeline = [{ $match: { daw: 'Logic Audio X' }} ]; aggregate.append(pipeline);
Aggregate.prototype.append = function () { var args = utils.args(arguments) , arg; if (!args.every(isOperator)) { throw new Error("Arguments must be aggregate pipeline operators"); } this._pipeline = this._pipeline.concat(args); return this; }
Aggregate#bind(
model
)Binds this aggregate to a model.
Parameters:
model
<Model> the model to which the aggregate is to be bound
show codeReturns:
Aggregate.prototype.bind = function (model) { this._model = model; return this; }
Aggregate#exec(
[callback]
)Executes the aggregate pipeline on the currently bound Model.
Parameters:
[callback]
<Function>
Returns:
- <Promise>
See:
show codeExample:
aggregate.exec(callback); // Because a promise is returned, the `callback` is optional. var promise = aggregate.exec(); promise.then(..);
Aggregate.prototype.exec = function (callback) { var promise = new Promise(); if (callback) { promise.addBack(callback); } if (!this._pipeline.length) { promise.error(new Error("Aggregate has empty pipeline")); return promise; } if (!this._model) { promise.error(new Error("Aggregate not bound to any Model")); return promise; } this._model .collection .aggregate(this._pipeline, this.options || {}, promise.resolve.bind(promise)); return promise; }
Aggregate#group(
arg
)Appends a new custom $group operator to this aggregate pipeline.
Parameters:
arg
<Object> $group operator contents
Returns:
See:
Examples:
aggregate.group({ _id: "$department" });
isOperator(
obj
)Checks whether an object is likely a pipeline operator
Parameters:
obj
<Object> object to check
show codeReturns:
- <Boolean>
function isOperator (obj) { var k; if ('object' !== typeof obj) { return false; } k = Object.keys(obj); return 1 === k.length && k.some(function (key) { return '$' === key[0]; }); }
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:
aggregate.limit(10);
Aggregate#match(
arg
)Appends a new custom $match operator to this aggregate pipeline.
Parameters:
arg
<Object> $match operator contents
Returns:
See:
Examples:
aggregate.match({ department: { $in: [ "sales", "engineering" } } });
Aggregate#near(
parameters
)Appends a new $geoNear operator to this aggregate pipeline.
Parameters:
parameters
<Object>
Returns:
See:
NOTE:
MUST be used as the first operator in the pipeline.
Examples:
aggregate.near({ near: [40.724, -73.997], distanceField: "dist.calculated", // required maxDistance: 0.008, query: { type: "public" }, includeLocs: "dist.location", uniqueDocs: true, num: 5 });
Aggregate#project(
arg
)Appends a new $project operator to this aggregate pipeline.
Returns:
See:
show codeMongoose query selection syntax is also supported.
Examples:
// include a, include b, exclude _id aggregate.project("a b -_id"); // or you may use object notation, useful when // you have keys already prefixed with a "-" aggregate.project({a: 1, b: 1, _id: 0}); // reshaping documents aggregate.project({ newField: '$b.nested' , plusTen: { $add: ['$val', 10]} , sub: { name: '$a' } }) // etc aggregate.project({ salary_k: { $divide: [ "$salary", 1000 ] } });
Aggregate.prototype.project = function (arg) { var fields = {}; if ('object' === typeof arg && !util.isArray(arg)) { Object.keys(arg).forEach(function (field) { fields[field] = arg[field]; }); } else if (1 === arguments.length && 'string' === typeof arg) { arg.split(/\s+/).forEach(function (field) { if (!field) return; var include = '-' == field[0] ? 0 : 1; if (include === 0) field = field.substring(1); fields[field] = include; }); } else { throw new Error("Invalid project() argument. Must be string or object"); } return this.append({ $project: fields }); }
Aggregate#read(
pref
,[tags]
)Sets the readPreference option for the aggregation query.
Parameters:
show codeExample:
Model.aggregate(..).read('primaryPreferred').exec(callback)
Aggregate.prototype.read = function (pref) { if (!this.options) this.options = {}; read.apply(this, arguments); return this; }
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:
aggregate.skip(10);
Aggregate#sort(
arg
)Appends a new $sort operator to this aggregate pipeline.
Returns:
- <Query> this
See:
show codeIf 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:
// these are equivalent aggregate.sort({ field: 'asc', test: -1 }); aggregate.sort('field -test');
Aggregate.prototype.sort = function (arg) { // TODO refactor to reuse the query builder logic var sort = {}; if ('Object' === arg.constructor.name) { var desc = ['desc', 'descending', -1]; Object.keys(arg).forEach(function (field) { sort[field] = desc.indexOf(arg[field]) === -1 ? 1 : -1; }); } else if (1 === arguments.length && 'string' == typeof arg) { arg.split(/\s+/).forEach(function (field) { if (!field) return; var ascend = '-' == field[0] ? -1 : 1; if (ascend === -1) field = field.substring(1); sort[field] = ascend; }); } else { throw new TypeError('Invalid sort() argument. Must be a string or object.'); } return this.append({ $sort: sort }); }
Aggregate#unwind(
fields
)Appends new custom $unwind operator(s) to this aggregate pipeline.
Parameters:
fields
<String> the field(s) to unwind
Returns:
See:
show codeExamples:
aggregate.unwind("tags"); aggregate.unwind("a", "b", "c");
Aggregate.prototype.unwind = function () { var args = utils.args(arguments); return this.append.apply(this, args.map(function (arg) { return { $unwind: '$' + arg }; })); }
- connection.js
Connection(
base
)Connection constructor
Parameters:
base
<Mongoose> a mongoose instance
Inherits:
Events:
connecting
: Emitted whenconnection.{open,openSet}()
is executed on this connection.connected
: Emitted when this connection successfully connects to the db. May be emitted multiple times inreconnected
scenarios.open
: Emitted after weconnected
andonOpen
is executed on all of this connections models.disconnecting
: Emitted whenconnection.close()
was executed.disconnected
: Emitted after getting disconnected from the db.close
: Emitted after wedisconnected
andonClose
executed on all of this connections models.reconnected
: Emitted after weconnected
and subsequentlydisconnected
, followed by successfully another successfull connection.error
: Emitted when an error occurs on this connection.fullsetup
: Emitted in a replica-set scenario, when all nodes specified in the connection string are connected.
show codeFor practical reasons, a Connection equals a Db.
function Connection (base) { this.base = base; this.collections = {}; this.models = {}; this.replica = false; this.hosts = null; this.host = null; this.port = null; this.user = null; this.pass = null; this.name = null; this.options = null; this.otherDbs = []; this._readyState = STATES.disconnected; this._closeCalled = false; this._hasOpened = false; };
Connection#open(
connection_string
,[database]
,[port]
,[options]
,[callback]
)Opens the connection to MongoDB.
Parameters:
See:
show codeoptions
is a hash with the following possible properties:db - passed to the connection db instance server - passed to the connection server instance(s) replset - passed to the connection ReplSet instance user - username for authentication pass - password for authentication auth - options for authentication (see http://mongodb.github.com/node-mongodb-native/api-generated/db.html#authenticate)
Notes:
Mongoose forces the db option
forceServerObjectId
false and cannot be overridden.
Mongoose defaults the serverauto_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.
Connection.prototype.open = function (host, database, port, options, callback) { var self = this , parsed , uri; if ('string' === typeof database) { switch (arguments.length) { case 2: port = 27017; case 3: switch (typeof port) { case 'function': callback = port, port = 27017; break; case 'object': options = port, port = 27017; break; } break; case 4: if ('function' === typeof options) callback = options, options = {}; } } else { switch (typeof database) { case 'function': callback = database, database = undefined; break; case 'object': options = database; database = undefined; callback = port; break; } if (!rgxProtocol.test(host)) { host = 'mongodb://' + host; } try { parsed = muri(host); } catch (err) { this.error(err, callback); return this; } database = parsed.db; host = parsed.hosts[0].host || parsed.hosts[0].ipc; port = parsed.hosts[0].port || 27017; } this.options = this.parseOptions(options, parsed && parsed.options); // make sure we can open if (STATES.disconnected !== this.readyState) { var err = new Error('Trying to open unclosed connection.'); err.state = this.readyState; this.error(err, callback); return this; } if (!host) { this.error(new Error('Missing hostname.'), callback); return this; } if (!database) { this.error(new Error('Missing database name.'), callback); return this; } // authentication if (options && options.user && options.pass) { this.user = options.user; this.pass = options.pass; } else if (parsed && parsed.auth) { this.user = parsed.auth.user; this.pass = parsed.auth.pass; // Check hostname for user/pass } else if (/@/.test(host) && /:/.test(host.split('@')[0])) { host = host.split('@'); var auth = host.shift().split(':'); host = host.pop(); this.user = auth[0]; this.pass = auth[1]; } else { this.user = this.pass = undefined; } this.name = database; this.host = host; this.port = port; this._open(callback); return this; };
Connection#openSet(
uris
,[database]
,[options]
,[callback]
)Opens the connection to a replica set.
Parameters:
See:
show codeExample:
var db = mongoose.createConnection(); db.openSet("mongodb://user:pwd@localhost:27020/testing,mongodb://example.com:27020,mongodb://localhost:27019");
The database name and/or auth need only be included in one URI.
Theoptions
is a hash which is passed to the internal driver connection object.Valid
options
db - passed to the connection db instance server - passed to the connection server instance(s) replset - passed to the connection ReplSetServer instance user - username for authentication pass - password for authentication auth - options for authentication (see http://mongodb.github.com/node-mongodb-native/api-generated/db.html#authenticate) mongos - Boolean - if true, enables High Availability support for mongos
Options passed take precedence over options included in connection strings.
Notes:
If connecting to multiple mongos servers, set the
mongos
option to true.conn.open('mongodb://mongosA:27501,mongosB:27501', { mongos: true }, cb);
Mongoose forces the db option
forceServerObjectId
false and cannot be overridden.
Mongoose defaults the serverauto_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.
Connection.prototype.openSet = function (uris, database, options, callback) { if (!rgxProtocol.test(uris)) { uris = 'mongodb://' + uris; } var self = this; switch (arguments.length) { case 3: switch (typeof database) { case 'string': this.name = database; break; case 'object': callback = options; options = database; database = null; break; } if ('function' === typeof options) { callback = options; options = {}; } break; case 2: switch (typeof database) { case 'string': this.name = database; break; case 'function': callback = database, database = null; break; case 'object': options = database, database = null; break; } } var parsed; try { parsed = muri(uris); } catch (err) { this.error(err, callback); return this; } if (!this.name) { this.name = parsed.db; } this.hosts = parsed.hosts; this.options = this.parseOptions(options, parsed && parsed.options); this.replica = true; if (!this.name) { this.error(new Error('No database name provided for replica set'), callback); return this; } // authentication if (options && options.user && options.pass) { this.user = options.user; this.pass = options.pass; } else if (parsed && parsed.auth) { this.user = parsed.auth.user; this.pass = parsed.auth.pass; } else { this.user = this.pass = undefined; } this._open(callback); return this; };
Connection#error(
err
,callback
)error
show codeGraceful error handling, passes error to callback
if available, else emits error on the connection.Connection.prototype.error = function (err, callback) { if (callback) return callback(err); this.emit('error', err); }
Connection#_open(
callback
)Handles opening the connection with the appropriate method based on connection type.
show codeParameters:
callback
<Function>
Connection.prototype._open = function (callback) { this.readyState = STATES.connecting; this._closeCalled = false; var self = this; var method = this.replica ? 'doOpenSet' : 'doOpen'; // open connection this[method](function (err) { if (err) { self.readyState = STATES.disconnected; if (self._hasOpened) { if (callback) callback(err); } else { self.error(err, callback); } return; } self.onOpen(callback); }); }
Connection#onOpen()
Called when the connection is opened
show codeConnection.prototype.onOpen = function (callback) { var self = this; function open (err) { if (err) { self.readyState = STATES.disconnected; if (self._hasOpened) { if (callback) callback(err); } else { self.error(err, callback); } return; } self.readyState = STATES.connected; // avoid having the collection subscribe to our event emitter // to prevent 0.3 warning for (var i in self.collections) self.collections[i].onOpen(); callback && callback(); self.emit('open'); }; // re-authenticate if (self.user && self.pass) { self.db.authenticate(self.user, self.pass, self.options.auth, open); } else open(); };
Connection#close(
[callback]
)Closes the connection
Parameters:
[callback]
<Function> optional
show codeReturns:
- <Connection> self
Connection.prototype.close = function (callback) { var self = this; this._closeCalled = true; switch (this.readyState){ case 0: // disconnected callback && callback(); break; case 1: // connected this.readyState = STATES.disconnecting; this.doClose(function(err){ if (err){ self.error(err, callback); } else { self.onClose(); callback && callback(); } }); break; case 2: // connecting this.once('open', function(){ self.close(callback); }); break; case 3: // disconnecting if (!callback) break; this.once('close', function () { callback(); }); break; } return this; };
Connection#onClose()
Called when the connection closes
show codeConnection.prototype.onClose = function () { this.readyState = STATES.disconnected; // avoid having the collection subscribe to our event emitter // to prevent 0.3 warning for (var i in this.collections) this.collections[i].onClose(); this.emit('close'); };
Connection#collection(
name
,[options]
)Retrieves a collection, creating it if not cached.
Returns:
- <Collection> collection instance
show codeNot typically needed by applications. Just talk to your collection through your model.
Connection.prototype.collection = function (name, options) { if (!(name in this.collections)) this.collections[name] = new Collection(name, this, options); return this.collections[name]; };
Connection#model(
name
,[schema]
,[collection]
)Defines or retrieves a model.
Parameters:
Returns:
- <Model> The compiled model
See:
show codevar mongoose = require('mongoose'); var db = mongoose.createConnection(..); db.model('Venue', new Schema(..)); var Ticket = db.model('Ticket', new Schema(..)); var Venue = db.model('Venue');
When no
collection
argument is passed, Mongoose produces a collection name by passing the modelname
to the utils.toCollectionName method. This method pluralizes the name. If you don't like this behavior, either pass a collection name or set your schemas collection name option.Example:
var schema = new Schema({ name: String }, { collection: 'actor' }); // or schema.set('collection', 'actor'); // or var collectionName = 'actor' var M = conn.model('Actor', schema, collectionName)
Connection.prototype.model = function (name, schema, collection) { // collection name discovery if ('string' == typeof schema) { collection = schema; schema = false; } if (utils.isObject(schema) && !(schema instanceof Schema)) { schema = new Schema(schema); } if (this.models[name] && !collection) { // model exists but we are not subclassing with custom collection if (schema instanceof Schema && schema != this.models[name].schema) { throw new MongooseError.OverwriteModelError(name); } return this.models[name]; } var opts = { cache: false, connection: this } var model; if (schema instanceof Schema) { // compile a model model = this.base.model(name, schema, collection, opts) // only the first model with this name is cached to allow // for one-offs with custom collection names etc. if (!this.models[name]) { this.models[name] = model; } model.init(); return model; } if (this.models[name] && collection) { // subclassing current model with alternate collection model = this.models[name]; schema = model.prototype.schema; var sub = model.__subclass(this, schema, collection); // do not cache the sub model return sub; } // lookup model in mongoose module model = this.base.models[name]; if (!model) { throw new MongooseError.MissingSchemaError(name); } if (this == model.prototype.db && (!collection || collection == model.collection.name)) { // model already uses this connection. // only the first model with this name is cached to allow // for one-offs with custom collection names etc. if (!this.models[name]) { this.models[name] = model; } return model; } return this.models[name] = model.__subclass(this, schema, collection); }
Connection#modelNames()
Returns an array of model names created on this connection.
show codeReturns:
- <Array>
Connection.prototype.modelNames = function () { return Object.keys(this.models); }
Connection#setProfiling(
level
,[ms]
,callback
)Set profiling level.
show codeParameters:
Connection.prototype.setProfiling = function (level, ms, callback) { if (STATES.connected !== this.readyState) { return this.on('open', this.setProfiling.bind(this, level, ms, callback)); } if (!callback) callback = ms, ms = 100; var cmd = {}; switch (level) { case 0: case 'off': cmd.profile = 0; break; case 1: case 'slow': cmd.profile = 1; if ('number' !== typeof ms) { ms = parseInt(ms, 10); if (isNaN(ms)) ms = 100; } cmd.slowms = ms; break; case 2: case 'all': cmd.profile = 2; break; default: return callback(new Error('Invalid profiling level: '+ level)); } this.db.executeDbCommand(cmd, function (err, resp) { if (err) return callback(err); var doc = resp.documents[0]; err = 1 === doc.ok ? null : new Error('Could not set profiling level to: '+ level) callback(err, doc); }); };
Connection#db
The mongodb.Db instance, set when the connection is opened
show codeConnection.prototype.db;
Connection#collections
A hash of the collections associated with this connection
show codeConnection.prototype.collections;
Connection#readyState
Connection ready state
- 0 = disconnected
- 1 = connected
- 2 = connecting
- 3 = disconnecting
Each state change emits its associated event name.
Example
show codeconn.on('connected', callback); conn.on('disconnected', callback);
Object.defineProperty(Connection.prototype, 'readyState', { get: function(){ return this._readyState; } , set: function (val) { if (!(val in STATES)) { throw new Error('Invalid connection state: ' + val); } if (this._readyState !== val) { this._readyState = val; // loop over the otherDbs on this connection and change their state for (var i=0; i < this.otherDbs.length; i++) { this.otherDbs[i].readyState = val; } if (STATES.connected === val) this._hasOpened = true; this.emit(STATES[val]); } } });
- document.js
Document#$__fullPath(
[path]
)Returns the full path to this document.
Parameters:
[path]
<String>
Returns:
- <String>
Document#$__set()
Handles the actual setting of the value and marking the path modified if appropriate.
Document#$__setSchema(
schema
)Assigns/compiles
schema
into this documents prototype.Parameters:
schema
<Schema>
Document#$__storeShard()
Stores the current values of the shard keys.
Note:
Shard key values do not / are not allowed to change.
Document#$__try(
fn
,scope
)Catches errors that occur during execution of
fn
and stores them to later be passed whensave()
is executed.Document(
obj
,[opts]
,[skipId]
)Document constructor.
Parameters:
Inherits:
show codeEvents:
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
function Document (obj, fields, skipId) { this.$__ = new InternalCache; this.isNew = true; this.errors = undefined; var schema = this.schema; if ('boolean' === typeof fields) { this.$__.strictMode = fields; fields = undefined; } else { this.$__.strictMode = schema.options && schema.options.strict; this.$__.selected = fields; } var required = schema.requiredPaths(); for (var i = 0; i < required.length; ++i) { this.$__.activePaths.require(required[i]); } setMaxListeners.call(this, 0); this._doc = this.$__buildDoc(obj, fields, skipId); if (obj) { this.set(obj, undefined, true); } this.$__registerHooks(); }
Document#equals(
doc
)Returns true if the Document stores the same data as doc.
Parameters:
doc
<Document> a document to compare
Returns:
- <Boolean>
show codeDocuments are considered equal when they have matching
_id
s.Document.prototype.equals = function (doc) { var tid = this.get('_id'); var docid = doc.get('_id'); return tid && tid.equals ? tid.equals(docid) : tid === docid; }
Document#get(
path
,[type]
)Returns the value of a path.
Parameters:
show codeExample
// path doc.get('age') // 47 // dynamic casting to a string doc.get('age', String) // "47"
Document.prototype.get = function (path, type) { var adhocs; if (type) { adhocs = this.$__.adhocPaths || (this.$__.adhocPaths = {}); adhocs[path] = Schema.interpretAsType(path, type); } var schema = this.$__path(path) || this.schema.virtualpath(path) , pieces = path.split('.') , obj = this._doc; for (var i = 0, l = pieces.length; i < l; i++) { obj = undefined === obj || null === obj ? undefined : obj[pieces[i]]; } if (schema) { obj = schema.applyGetters(obj, this); } return obj; };
Document#getValue(
path
)Gets a raw value from a path (no getters)
show codeParameters:
path
<String>
Document.prototype.getValue = function (path) { return utils.getValue(path, this._doc); }
Document#init(
doc
,fn
)Initializes the document without setters or marking anything modified.
show codeCalled internally after a document is returned from mongodb.
Document.prototype.init = function (doc, opts, fn) { // do not prefix this method with $__ since its // used by public hooks if ('function' == typeof opts) { fn = opts; opts = null; } this.isNew = false; // handle docs with populated paths if (doc._id && opts && opts.populated && opts.populated.length) { var id = String(doc._id); for (var i = 0; i < opts.populated.length; ++i) { var item = opts.populated[i]; this.populated(item.path, item._docs[id], item); } } init(this, doc, this._doc); this.$__storeShard(); this.emit('init', this); if (fn) fn(null); return this; };
Document#inspect()
Helper for console.log
show codeDocument.prototype.inspect = function (options) { var opts = options && 'Object' == options.constructor.name ? options : this.schema.options.toObject ? clone(this.schema.options.toObject) : {}; opts.minimize = false; return inspect(this.toObject(opts)); };
Document#invalidate(
path
,errorMsg
,value
)Marks a path as invalid, causing validation to fail.
Parameters:
show codeThe
errorMsg
argument will become the message of theValidationError
.The
value
argument (if passed) will be available through theValidationError.value
property.doc.invalidate('size', 'must be less than 20', 14); doc.validate(function (err) { console.log(err) // prints { message: 'Validation failed', name: 'ValidationError', errors: { size: { message: 'must be less than 20', name: 'ValidatorError', path: 'size', type: 'user defined', value: 14 } } } })
Document.prototype.invalidate = function (path, err, val) { if (!this.$__.validationError) { this.$__.validationError = new ValidationError(this); } if (!err || 'string' === typeof err) { err = new ValidatorError(path, err, 'user defined', val) } this.$__.validationError.errors[path] = err; }
Document#isDirectModified(
path
)Returns true if
path
was directly set and modified, else false.Parameters:
path
<String>
Returns:
- <Boolean>
show codeExample
doc.set('documents.0.title', 'changed'); doc.isDirectModified('documents.0.title') // true doc.isDirectModified('documents') // false
Document.prototype.isDirectModified = function (path) { return (path in this.$__.activePaths.states.modify); };
Document#isInit(
path
)Checks if
path
was initialized.Parameters:
path
<String>
show codeReturns:
- <Boolean>
Document.prototype.isInit = function (path) { return (path in this.$__.activePaths.states.init); };
Document#isModified(
[path]
)Returns true if this document was modified, else false.
Parameters:
[path]
<String> optional
Returns:
- <Boolean>
show codeIf
path
is given, checks if a path or any full path containingpath
as part of its path chain has been modified.Example
doc.set('documents.0.title', 'changed'); doc.isModified() // true doc.isModified('documents') // true doc.isModified('documents.0.title') // true doc.isDirectModified('documents') // false
Document.prototype.isModified = function (path) { return path ? !!~this.modifiedPaths().indexOf(path) : this.$__.activePaths.some('modify'); };
Document#isSelected(
path
)Checks if
path
was selected in the source query which initialized this document.Parameters:
path
<String>
Returns:
- <Boolean>
show codeExample
Thing.findOne().select('name').exec(function (err, doc) { doc.isSelected('name') // true doc.isSelected('age') // false })
Document.prototype.isSelected = function isSelected (path) { if (this.$__.selected) { if ('_id' === path) { return 0 !== this.$__.selected._id; } var paths = Object.keys(this.$__.selected) , i = paths.length , inclusive = false , cur if (1 === i && '_id' === paths[0]) { // only _id was selected. return 0 === this.$__.selected._id; } while (i--) { cur = paths[i]; if ('_id' == cur) continue; inclusive = !! this.$__.selected[cur]; break; } if (path in this.$__.selected) { return inclusive; } i = paths.length; var pathDot = path + '.'; while (i--) { cur = paths[i]; if ('_id' == cur) continue; if (0 === cur.indexOf(pathDot)) { return inclusive; } if (0 === pathDot.indexOf(cur + '.')) { return inclusive; } } return ! inclusive; } return true; }
Document#markModified(
path
)Marks the path as having pending changes to write to the db.
Parameters:
path
<String> the path to mark modified
show codeVery helpful when using Mixed types.
Example:
doc.mixed.type = 'changed'; doc.markModified('mixed.type'); doc.save() // changes to mixed.type are now persisted
Document.prototype.markModified = function (path) { this.$__.activePaths.modify(path); }
Document#modifiedPaths()
Returns the list of paths that have been modified.
show codeReturns:
- <Array>
Document.prototype.modifiedPaths = function () { var directModifiedPaths = Object.keys(this.$__.activePaths.states.modify); return directModifiedPaths.reduce(function (list, path) { var parts = path.split('.'); return list.concat(parts.reduce(function (chains, part, i) { return chains.concat(parts.slice(0, i).concat(part).join('.')); }, [])); }, []); };
Document#populate(
[path]
,[callback]
)Populates document references, executing the
callback
when complete.Parameters:
Returns:
- <Document> this
See:
show codeExample:
doc .populate('company') .populate({ path: 'notes', match: /airline/, select: 'text', model: 'modelName' options: opts }, function (err, user) { assert(doc._id == user._id) // the document itself is passed }) // summary doc.populate(path) // not executed doc.populate(options); // not executed doc.populate(path, callback) // executed doc.populate(options, callback); // executed doc.populate(callback); // executed
NOTE:
Population does not occur unless a
callback
is passed.
Passing the same path a second time will overwrite the previous path options.
See Model.populate() for explaination of options.Document.prototype.populate = function populate () { if (0 === arguments.length) return this; var pop = this.$__.populate || (this.$__.populate = {}); var args = utils.args(arguments); var fn; if ('function' == typeof args[args.length-1]) { fn = args.pop(); } // allow `doc.populate(callback)` if (args.length) { // use hash to remove duplicate paths var res = utils.populate.apply(null, args); for (var i = 0; i < res.length; ++i) { pop[res[i].path] = res[i]; } } if (fn) { var paths = utils.object.vals(pop); this.$__.populate = undefined; this.constructor.populate(this, paths, fn); } return this; }
Document#populated(
path
)Gets _id(s) used during population of the given
path
.Parameters:
path
<String>
show codeExample:
Model.findOne().populate('author').exec(function (err, doc) { console.log(doc.author.name) // Dr.Seuss console.log(doc.populated('author')) // '5144cf8050f071d979c118a7' })
If the path was not populated, undefined is returned.
Document.prototype.populated = function (path, val, options) { // val and options are internal if (null == val) { if (!this.$__.populated) return undefined; var v = this.$__.populated[path]; if (v) return v.value; return undefined; } // internal if (true === val) { if (!this.$__.populated) return undefined; return this.$__.populated[path]; } this.$__.populated || (this.$__.populated = {}); this.$__.populated[path] = { value: val, options: options }; return val; }
Document#set(
path
,val
,[type]
,[options]
)Sets the value of a path, or many paths.
Parameters:
show codeExample:
// path, value doc.set(path, value) // object doc.set({ path : value , path2 : { path : value } }) // only-the-fly cast to number doc.set(path, value, Number) // only-the-fly cast to string doc.set(path, value, String) // changing strict mode behavior doc.set(path, value, { strict: false });
Document.prototype.set = function (path, val, type, options) { if (type && 'Object' == type.constructor.name) { options = type; type = undefined; } var merge = options && options.merge , adhoc = type && true !== type , constructing = true === type , adhocs var strict = options && 'strict' in options ? options.strict : this.$__.strictMode; if (adhoc) { adhocs = this.$__.adhocPaths || (this.$__.adhocPaths = {}); adhocs[path] = Schema.interpretAsType(path, type); } if ('string' !== typeof path) { // new Document({ key: val }) if (null === path || undefined === path) { var _ = path; path = val; val = _; } else { var prefix = val ? val + '.' : ''; if (path instanceof Document) path = path._doc; var keys = Object.keys(path) , i = keys.length , pathtype , key while (i--) { key = keys[i]; pathtype = this.schema.pathType(prefix + key); if (null != path[key] // need to know if plain object - no Buffer, ObjectId, ref, etc && utils.isObject(path[key]) && (!path[key].constructor || 'Object' == path[key].constructor.name) && 'virtual' != pathtype && !(this.$__path(prefix + key) instanceof MixedSchema) && !(this.schema.paths[key] && this.schema.paths[key].options.ref) ) { this.set(path[key], prefix + key, constructing); } else if (strict) { if ('real' === pathtype || 'virtual' === pathtype) { this.set(prefix + key, path[key], constructing); } else if ('throw' == strict) { throw new Error("Field `" + key + "` is not in schema."); } } else if (undefined !== path[key]) { this.set(prefix + key, path[key], constructing); } } return this; } } // ensure _strict is honored for obj props // docschema = new Schema({ path: { nest: 'string' }}) // doc.set('path', obj); var pathType = this.schema.pathType(path); if ('nested' == pathType && val && utils.isObject(val) && (!val.constructor || 'Object' == val.constructor.name)) { if (!merge) this.setValue(path, null); this.set(val, path, constructing); return this; } var schema; var parts = path.split('.'); if ('adhocOrUndefined' == pathType && strict) { // check for roots that are Mixed types var mixed; for (var i = 0; i < parts.length; ++i) { var subpath = parts.slice(0, i+1).join('.'); schema = this.schema.path(subpath); if (schema instanceof MixedSchema) { // allow changes to sub paths of mixed types mixed = true; break; } } if (!mixed) { if ('throw' == strict) { throw new Error("Field `" + path + "` is not in schema."); } return this; } } else if ('virtual' == pathType) { schema = this.schema.virtualpath(path); schema.applySetters(val, this); return this; } else { schema = this.$__path(path); } var pathToMark; // When using the $set operator the path to the field must already exist. // Else mongodb throws: "LEFT_SUBFIELD only supports Object" if (parts.length <= 1) { pathToMark = path; } else { for (var i = 0; i < parts.length; ++i) { var subpath = parts.slice(0, i+1).join('.'); if (this.isDirectModified(subpath) // earlier prefixes that are already // marked as dirty have precedence || this.get(subpath) === null) { pathToMark = subpath; break; } } if (!pathToMark) pathToMark = path; } // if this doc is being constructed we should not trigger getters var priorVal = constructing ? undefined : this.get(path); if (!schema || undefined === val) { this.$__set(pathToMark, path, constructing, parts, schema, val, priorVal); return this; } var self = this; var shouldSet = this.$__try(function(){ val = schema.applySetters(val, self, false, priorVal); }); if (shouldSet) { this.$__set(pathToMark, path, constructing, parts, schema, val, priorVal); } return this; }
Document#setValue(
path
,value
)Sets a raw value for a path (no casting, setters, transformations)
show codeDocument.prototype.setValue = function (path, val) { utils.setValue(path, val, this._doc); return this; }
Document#toJSON(
options
)The return value of this method is used in calls to JSON.stringify(doc).
Parameters:
options
<Object>
Returns:
- <Object>
show codeThis 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.schema.set('toJSON', { virtuals: true })
See schema options for details.
Document.prototype.toJSON = function (options) { // check for object type since an array of documents // being stringified passes array indexes instead // of options objects. JSON.stringify([doc, doc]) // The second check here is to make sure that populated documents (or // subdocuments) use their own options for `.toJSON()` instead of their // parent's if (!(options && 'Object' == options.constructor.name) || ((!options || options.json) && this.schema.options.toJSON)) { options = this.schema.options.toJSON ? clone(this.schema.options.toJSON) : {}; } options.json = true; return this.toObject(options); };
Document#toObject(
[options]
)Converts this document into a plain javascript object, ready for storage in MongoDB.
Parameters:
[options]
<Object>
Returns:
- <Object> js object
See:
show codeBuffers are converted to instances of mongodb.Binary for proper storage.
Options:
getters
apply all getters (path and virtual getters)virtuals
apply virtual getters (can overridegetters
option)minimize
remove empty objects (defaults to true)transform
a transform function to apply to the resulting document before returning
Getters/Virtuals
Example of only applying path getters
doc.toObject({ getters: true, virtuals: false })
Example of only applying virtual getters
doc.toObject({ virtuals: true })
Example of applying both path and virtual getters
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.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
function (doc, ret, options) {}
doc
The mongoose document which is being convertedret
The plain object representation which has been convertedoptions
The options in use (either schema options or the options passed inline)
Example
// specify the transform schema option if (!schema.options.toObject) schema.options.toObject = {}; schema.options.toObject.transform = function (doc, ret, options) { // remove the _id of every document before returning the result delete ret._id; } // without the transformation in the schema doc.toObject(); // { _id: 'anId', name: 'Wreck-it Ralph' } // with the transformation 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:
if (!schema.options.toObject) schema.options.toObject = {}; schema.options.toObject.transform = function (doc, ret, options) { return { movie: ret.name } } // without the transformation in the schema doc.toObject(); // { _id: 'anId', name: 'Wreck-it Ralph' } // with the transformation 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:
function xform (doc, ret, options) { return { inline: ret.name, custom: true } } // pass the transform as an inline option doc.toObject({ transform: xform }); // { inline: 'Wreck-it Ralph', custom: true }
Note: if you call
toObject
and pass any options, the transform declared in your schema options will not be applied. To force its application passtransform: true
if (!schema.options.toObject) schema.options.toObject = {}; schema.options.toObject.hide = '_id'; schema.options.toObject.transform = function (doc, ret, options) { if (options.hide) { options.hide.split(' ').forEach(function (prop) { delete ret[prop]; }); } } var doc = new Doc({ _id: 'anId', secret: 47, name: 'Wreck-it Ralph' }); doc.toObject(); // { secret: 47, name: 'Wreck-it Ralph' } doc.toObject({ hide: 'secret _id' }); // { _id: 'anId', secret: 47, name: 'Wreck-it Ralph' } doc.toObject({ hide: 'secret _id', transform: true }); // { name: 'Wreck-it Ralph' }
Transforms are applied to the document and each of its sub-documents. To determine whether or not you are currently operating on a sub-document you might use the following guard:
if ('function' == typeof doc.ownerDocument) { // working with a sub doc }
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.
Document.prototype.toObject = function (options) { if (options && options.depopulate && this.$__.wasPopulated) { // populated paths that we set to a document return clone(this._id, options); } // When internally saving this document we always pass options, // bypassing the custom schema options. if (!(options && 'Object' == options.constructor.name)) { options = this.schema.options.toObject ? clone(this.schema.options.toObject) : {}; } ;('minimize' in options) || (options.minimize = this.schema.options.minimize); var ret = clone(this._doc, options); if (options.virtuals || options.getters && false !== options.virtuals) { applyGetters(this, ret, 'virtuals', options); } if (options.getters) { applyGetters(this, ret, 'paths', options); } // In the case where a subdocument has its own transform function, we need to // check and see if the parent has a transform (options.transform) and if the // child schema has a transform (this.schema.options.toObject) In this case, // we need to adjust options.transform to be the child schema's transform and // not the parent schema's if (true === options.transform || (this.schema.options.toObject && options.transform)) { var opts = options.json ? this.schema.options.toJSON : this.schema.options.toObject; if (opts) { options.transform = opts.transform; } } if ('function' == typeof options.transform) { var xformed = options.transform(this, ret, options); if ('undefined' != typeof xformed) ret = xformed; } return ret; };
Document#update(
doc
,options
,callback
)Sends an update command with this document
_id
as the query selector.Returns:
- <Query>
See:
show codeExample:
weirdCar.update({$inc: {wheels:1}}, { w: 1 }, callback);
Valid options:
- same as in Model.update
Document.prototype.update = function update () { var args = utils.args(arguments); args.unshift({_id: this._id}); return this.constructor.update.apply(this.constructor, args); }
Document#validate(
cb
)Executes registered validation rules for this document.
Parameters:
cb
<Function> called after validation completes, passing an error if one occurred
show codeNote:
This method is called
pre
save and if a validation rule is violated, save is aborted and the error is returned to yourcallback
.Example:
doc.validate(function (err) { if (err) handleError(err); else // validation passed });
Document.prototype.validate = function (cb) { var self = this // only validate required fields when necessary var paths = Object.keys(this.$__.activePaths.states.require).filter(function (path) { if (!self.isSelected(path) && !self.isModified(path)) return false; return true; }); paths = paths.concat(Object.keys(this.$__.activePaths.states.init)); paths = paths.concat(Object.keys(this.$__.activePaths.states.modify)); paths = paths.concat(Object.keys(this.$__.activePaths.states.default)); if (0 === paths.length) { complete(); return this; } var validating = {} , total = 0; paths.forEach(validatePath); return this; function validatePath (path) { if (validating[path]) return; validating[path] = true; total++; process.nextTick(function(){ var p = self.schema.path(path); if (!p) return --total || complete(); var val = self.getValue(path); p.doValidate(val, function (err) { if (err) { self.invalidate( path , err , undefined , true // embedded docs ); } --total || complete(); }, self); }); } function complete () { var err = self.$__.validationError; self.$__.validationError = undefined; self.emit('validate', self); cb(err); } };
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 itsSchema
to false at construction time.
show codenew Schema({ name: String }, { id: false });
Document.prototype.id;
See:
- drivers/node-mongodb-native/collection.js
NativeCollection()
A node-mongodb-native collection implementation.
Inherits:
show codeAll methods methods from the node-mongodb-native driver are copied and wrapped in queue management.
function NativeCollection () { this.collection = null; MongooseCollection.apply(this, arguments); }
NativeCollection#getIndexes(
callback
)Retreives information about this collections indexes.
Parameters:
callback
<Function>
NativeCollection#onClose()
Called when the connection closes
show codeNativeCollection.prototype.onClose = function () { MongooseCollection.prototype.onClose.call(this); };
NativeCollection#onOpen()
Called when the connection opens.
show codeNativeCollection.prototype.onOpen = function () { var self = this; // always get a new collection in case the user changed host:port // of parent db instance when re-opening the connection. if (!self.opts.capped.size) { // non-capped return self.conn.db.collection(self.name, callback); } // capped return self.conn.db.collection(self.name, function (err, c) { if (err) return callback(err); // discover if this collection exists and if it is capped c.options(function (err, exists) { if (err) return callback(err); if (exists) { if (exists.capped) { callback(null, c); } else { var msg = 'A non-capped collection exists with the name: '+ self.name +' ' + ' To use this collection as a capped collection, please ' + 'first convert it. ' + ' http://www.mongodb.org/display/DOCS/Capped+Collections#CappedCollections-Convertingacollectiontocapped' err = new Error(msg); callback(err); } } else { // create var opts = utils.clone(self.opts.capped); opts.capped = true; self.conn.db.createCollection(self.name, opts, callback); } }); }); function callback (err, collection) { if (err) { // likely a strict mode error self.conn.emit('error', err); } else { self.collection = collection; MongooseCollection.prototype.onOpen.call(self); } }; };
- drivers/node-mongodb-native/connection.js
NativeConnection()
A node-mongodb-native connection implementation.
show codeInherits:
function NativeConnection() { MongooseConnection.apply(this, arguments); this._listening = false; };
NativeConnection#doClose(
fn
)Closes the connection
Parameters:
fn
<Function>
show codeReturns:
- <Connection> this
NativeConnection.prototype.doClose = function (fn) { this.db.close(); if (fn) fn(); return this; }
NativeConnection#doOpen(
fn
)Opens the connection to MongoDB.
Parameters:
fn
<Function>
show codeReturns:
- <Connection> this
NativeConnection.prototype.doOpen = function (fn) { if (this.db) { mute(this); } var server = new Server(this.host, this.port, this.options.server); this.db = new Db(this.name, server, this.options.db); var self = this; this.db.open(function (err) { if (err) return fn(err); listen(self); fn(); }); return this; };
NativeConnection#doOpenSet(
fn
)Opens a connection to a MongoDB ReplicaSet.
Parameters:
fn
<Function>
Returns:
- <Connection> this
show codeSee description of doOpen for server options. In this case
options.replset
is also passed to ReplSetServers.NativeConnection.prototype.doOpenSet = function (fn) { if (this.db) { mute(this); } var servers = [] , self = this; this.hosts.forEach(function (server) { var host = server.host || server.ipc; var port = server.port || 27017; servers.push(new Server(host, port, self.options.server)); }) var server = this.options.mongos ? new Mongos(servers, this.options.mongos) : new ReplSetServers(servers, this.options.replset); this.db = new Db(this.name, server, this.options.db); this.db.on('fullsetup', function () { self.emit('fullsetup') }); this.db.open(function (err) { if (err) return fn(err); fn(); listen(self); }); return this; };
NativeConnection#parseOptions(
passed
,[connStrOptions]
)Prepares default connection options for the node-mongodb-native driver.
Parameters:
show codeNOTE:
passed
options take precedence over connection string options.NativeConnection.prototype.parseOptions = function (passed, connStrOpts) { var o = passed || {}; o.db || (o.db = {}); o.auth || (o.auth = {}); o.server || (o.server = {}); o.replset || (o.replset = {}); o.server.socketOptions || (o.server.socketOptions = {}); o.replset.socketOptions || (o.replset.socketOptions = {}); var opts = connStrOpts || {}; Object.keys(opts).forEach(function (name) { switch (name) { case 'poolSize': if ('undefined' == typeof o.server.poolSize) { o.server.poolSize = o.replset.poolSize = opts[name]; } break; case 'slaveOk': if ('undefined' == typeof o.server.slave_ok) { o.server.slave_ok = opts[name]; } break; case 'autoReconnect': if ('undefined' == typeof o.server.auto_reconnect) { o.server.auto_reconnect = opts[name]; } break; case 'ssl': case 'socketTimeoutMS': case 'connectTimeoutMS': if ('undefined' == typeof o.server.socketOptions[name]) { o.server.socketOptions[name] = o.replset.socketOptions[name] = opts[name]; } break; case 'authdb': if ('undefined' == typeof o.auth.authdb) { o.auth.authdb = opts[name]; } break; case 'authSource': if ('undefined' == typeof o.auth.authSource) { o.auth.authSource = opts[name]; } break; case 'retries': case 'reconnectWait': case 'rs_name': if ('undefined' == typeof o.replset[name]) { o.replset[name] = opts[name]; } break; case 'replicaSet': if ('undefined' == typeof o.replset.rs_name) { o.replset.rs_name = opts[name]; } break; case 'readSecondary': if ('undefined' == typeof o.replset.read_secondary) { o.replset.read_secondary = opts[name]; } break; case 'nativeParser': if ('undefined' == typeof o.db.native_parser) { o.db.native_parser = opts[name]; } break; case 'w': case 'safe': case 'fsync': case 'journal': case 'wtimeoutMS': if ('undefined' == typeof o.db[name]) { o.db[name] = opts[name]; } break; case 'readPreference': if ('undefined' == typeof o.db.read_preference) { o.db.read_preference = opts[name]; } break; case 'readPreferenceTags': if ('undefined' == typeof o.db.read_preference_tags) { o.db.read_preference_tags = opts[name]; } break; } }) if (!('auto_reconnect' in o.server)) { o.server.auto_reconnect = true; } if (!o.db.read_preference) { // read from primaries by default o.db.read_preference = 'primary'; } // mongoose creates its own ObjectIds o.db.forceServerObjectId = false; // default safe using new nomenclature if (!('journal' in o.db || 'j' in o.db || 'fsync' in o.db || 'safe' in o.db || 'w' in o.db)) { o.db.w = 1; } validate(o); return o; }
NativeConnection#useDb(
name
)Switches to a different database using the same connection pool.
Parameters:
name
<String> The database name
Returns:
- <Connection> New Connection Object
show codeReturns a new connection object, with the new db.
NativeConnection.prototype.useDb = function (name) { // we have to manually copy all of the attributes... var newConn = new this.constructor(); newConn.name = name; newConn.base = this.base; newConn.collections = {}; newConn.models = {}; newConn.replica = this.replica; newConn.hosts = this.hosts; newConn.host = this.host; newConn.port = this.port; newConn.user = this.user; newConn.pass = this.pass; newConn.options = this.options; newConn._readyState = this._readyState; newConn._closeCalled = this._closeCalled; newConn._hasOpened = this._hasOpened; newConn._listening = false; // First, when we create another db object, we are not guaranteed to have a // db object to work with. So, in the case where we have a db object and it // is connected, we can just proceed with setting everything up. However, if // we do not have a db or the state is not connected, then we need to wait on // the 'open' event of the connection before doing the rest of the setup // the 'connected' event is the first time we'll have access to the db object var self = this; if (this.db && this.db._state == 'connected') { wireup(); } else { this.once('connected', wireup); } function wireup () { newConn.db = self.db.db(name); newConn.onOpen(); // setup the events appropriately listen(newConn); } newConn.name = name; // push onto the otherDbs stack, this is used when state changes this.otherDbs.push(newConn); newConn.otherDbs.push(this); return newConn; };
NativeConnection.STATES
Expose the possible connection states.
show codeNativeConnection.STATES = STATES;
- error/cast.js
CastError(
type
,value
)Casting Error constructor.
show codeInherits:
function CastError (type, value, path) { MongooseError.call(this, 'Cast to ' + type + ' failed for value "' + value + '" at path "' + path + '"'); Error.captureStackTrace(this, arguments.callee); this.name = 'CastError'; this.type = type; this.value = value; this.path = path; };
- error/messages.js
MongooseError#messages
The default built-in validator error messages. These may be customized.
// customize within each schema or globally like so var mongoose = require('mongoose'); mongoose.Error.messages.String.enum = "Your custom message for {PATH}.";
As you might have noticed, error messages support basic templating
{PATH}
is replaced with the invalid document path{VALUE}
is replaced with the invalid value{TYPE}
is replaced with the validator type such as "regexp", "min", or "user defined"{MIN}
is replaced with the declared min value for the Number.min validator{MAX}
is replaced with the declared max value for the Number.max validator
Click the "show code" link below to see all defaults.
show codevar msg = module.exports = exports = {}; msg.general = {}; msg.general.default = "Validator failed for path `{PATH}` with value `{VALUE}`"; msg.general.required = "Path `{PATH}` is required."; msg.Number = {}; msg.Number.min = "Path `{PATH}` ({VALUE}) is less than minimum allowed value ({MIN})."; msg.Number.max = "Path `{PATH}` ({VALUE}) is more than maximum allowed value ({MAX})."; msg.String = {}; msg.String.enum = "`{VALUE}` is not a valid enum value for path `{PATH}`."; msg.String.match = "Path `{PATH}` is invalid ({VALUE}).";
- error/validation.js
ValidationError(
instance
)Document Validation Error
Parameters:
instance
<Document>
show codeInherits:
function ValidationError (instance) { MongooseError.call(this, "Validation failed"); Error.captureStackTrace(this, arguments.callee); this.name = 'ValidationError'; this.errors = instance.errors = {}; };
ValidationError#toString()
Console.log helper
show codeValidationError.prototype.toString = function () { var ret = this.name + ': '; var msgs = []; Object.keys(this.errors).forEach(function (key) { if (this == this.errors[key]) return; msgs.push(String(this.errors[key])); }, this) return ret + msgs.join(', '); };
- error/validator.js
ValidatorError(
path
,msg
,val
)Schema validator error
show codeInherits:
function ValidatorError (path, msg, type, val) { if (!msg) msg = errorMessages.general.default; var message = this.formatMessage(msg, path, type, val); MongooseError.call(this, message); Error.captureStackTrace(this, arguments.callee); this.name = 'ValidatorError'; this.path = path; this.type = type; this.value = val; };
- error/version.js
VersionError()
Version Error constructor.
show codeInherits:
function VersionError () { MongooseError.call(this, 'No matching document found.'); Error.captureStackTrace(this, arguments.callee); this.name = 'VersionError'; };
- error.js
MongooseError(
msg
)MongooseError constructor
Parameters:
msg
<String> Error message
show codeInherits:
function MongooseError (msg) { Error.call(this); Error.captureStackTrace(this, arguments.callee); this.message = msg; this.name = 'MongooseError'; };
MongooseError.messages
The default built-in validator error messages.
show codeMongooseError.messages = require('./error/messages'); // backward compat MongooseError.Messages = MongooseError.messages;
See:
- model.js
Model#$where(
argument
)Creates a
Query
and specifies a$where
condition.Returns:
- <Query>
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.Blog.$where('this.comments.length > 5').exec(function (err, docs) {});
Model(
doc
)Model constructor
Parameters:
doc
<Object> values with which to create the document
Inherits:
Events:
error
: If listening to this event, it is emitted when a document was saved without passing a callback and anerror
occurred. If not listening, the event bubbles to the connection used to create this Model.index
: Emitted afterModel#ensureIndexes
completes. If an error occurred it is passed with the event.
show codeProvides the interface to MongoDB collections as well as creates document instances.
function Model (doc, fields, skipId) { Document.call(this, doc, fields, skipId); };
Model#increment()
Signal that we desire an increment of this documents version.
See:
show codeExample:
Model.findById(id, function (err, doc) { doc.increment(); doc.save(function (err) { .. }) })
Model.prototype.increment = function increment () { this.$__.version = VERSION_ALL; return this; }
Model#model(
name
)Returns another Model instance.
Parameters:
name
<String> model name
show codeExample:
var doc = new Tank; doc.model('User').findById(id, callback);
Model.prototype.model = function model (name) { return this.db.model(name); };
Model#remove(
[fn]
)Removes this document from the db.
Parameters:
[fn]
<Function> optional callback
show codeExample:
product.remove(function (err, product) { if (err) return handleError(err); Product.findById(product._id, function (err, product) { console.log(product) // null }) })
Model.prototype.remove = function remove (fn) { if (this.$__.removing) { this.$__.removing.addBack(fn); return this; } var promise = this.$__.removing = new Promise(fn) , where = this.$__where() , self = this , options = {} if (this.schema.options.safe) { options.safe = this.schema.options.safe; } this.collection.remove(where, options, tick(function (err) { if (err) { promise.error(err); promise = self = self.$__.removing = where = options = null; return; } self.emit('remove', self); promise.complete(self); promise = self = where = options = null; })); return this; };
Model#save(
[fn]
)Saves this document.
Parameters:
[fn]
<Function> optional callback
See:
show codeExample:
product.sold = Date.now(); product.save(function (err, product, numberAffected) { if (err) .. })
The callback will receive three parameters,
err
if an error occurred,product
which is the savedproduct
, andnumberAffected
which will be 1 when the document was found and updated in the database, otherwise 0.The
fn
callback is optional. If nofn
is passed and validation fails, the validation error will be emitted on the connection used to create this model.var db = mongoose.createConnection(..); var schema = new Schema(..); var Product = db.model('Product', schema); db.on('error', handleError);
However, if you desire more local error handling you can add an
error
listener to the model and handle errors there instead.Product.on('error', handleError);
Model.prototype.save = function save (fn) { var promise = new Promise(fn) , complete = handleSave(promise, this) , options = {} if (this.schema.options.safe) { options.safe = this.schema.options.safe; } if (this.isNew) { // send entire doc var obj = this.toObject({ depopulate: 1 }); if (!utils.object.hasOwnProperty(obj || {}, '_id')) { // documents must have an _id else mongoose won't know // what to update later if more changes are made. the user // wouldn't know what _id was generated by mongodb either // nor would the ObjectId generated my mongodb necessarily // match the schema definition. return complete(new Error('document must have an _id before saving')); } this.$__version(true, obj); this.collection.insert(obj, options, complete); this.$__reset(); this.isNew = false; this.emit('isNew', false); // Make it possible to retry the insert this.$__.inserting = true; } else { // Make sure we don't treat it as a new object on error, // since it already exists this.$__.inserting = false; var delta = this.$__delta(); if (delta) { if (delta instanceof Error) return complete(delta); var where = this.$__where(delta[0]); this.$__reset(); this.collection.update(where, delta[1], options, complete); } else { this.$__reset(); complete(null); } this.emit('isNew', false); } };
Model._getSchema(
path
)Finds the schema for
show codepath
. This is different than
callingschema.path
as it also resolves paths with
positional selectors (something.$.another.$.path).Model._getSchema = function _getSchema (path) { var schema = this.schema , pathschema = schema.path(path); if (pathschema) return pathschema; // look for arrays return (function search (parts, schema) { var p = parts.length + 1 , foundschema , trypath while (p--) { trypath = parts.slice(0, p).join('.'); foundschema = schema.path(trypath); if (foundschema) { if (foundschema.caster) { // array of Mixed? if (foundschema.caster instanceof Types.Mixed) { return foundschema.caster; } // Now that we found the array, we need to check if there // are remaining document paths to look up for casting. // Also we need to handle array.$.path since schema.path // doesn't work for that. // If there is no foundschema.schema we are dealing with // a path like array.$ if (p !== parts.length && foundschema.schema) { if ('$' === parts[p]) { // comments.$.comments.$.title return search(parts.slice(p+1), foundschema.schema); } else { // this is the last path of the selector return search(parts.slice(p), foundschema.schema); } } } return foundschema; } } })(path.split('.'), schema) }
Parameters:
path
<String>
Returns:
- <Schema>
Model.aggregate(
[...]
,[callback]
)Performs aggregations on the models collection.
show codeModel.aggregate = function aggregate () { var args = [].slice.call(arguments) , aggregate , callback; if ('function' === typeof args[args.length - 1]) { callback = args.pop(); } if (1 === args.length && util.isArray(args[0])) { aggregate = new Aggregate(args[0]); } else { aggregate = new Aggregate(args); } aggregate.bind(this); if ('undefined' === typeof callback) { return aggregate; } return aggregate.exec(callback); }
Parameters:
If a
callback
is passed, theaggregate
is executed and aPromise
is returned. If a callback is not passed, theaggregate
itself is returned.Example:
// Find the max balance of all accounts Users.aggregate( { $group: { _id: null, maxBalance: { $max: '$balance' }}} , { $project: { _id: 0, maxBalance: 1 }} , function (err, res) { if (err) return handleError(err); console.log(res); // [ { maxBalance: 98000 } ] }); // Or use the aggregation pipeline builder. Users.aggregate() .group({ _id: null, maxBalance: { $max: '$balance' } }) .select('-id maxBalance') .exec(function (err, res) { if (err) return handleError(err); console.log(res); // [ { maxBalance: 98 } ] });
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.count(
conditions
,[callback]
)Counts number of matching documents in a database collection.
show codeModel.count = function count (conditions, callback) { if ('function' === typeof conditions) callback = conditions, conditions = {}; // get the mongodb collection object var mq = new Query({}, {}, this, this.collection); return mq.count(conditions, callback); };
Returns:
- <Query>
Example:
Adventure.count({ type: 'jungle' }, function (err, count) { if (err) .. console.log('there are %d jungle adventures', count); });
Model.create(
doc(s)
,[fn]
)Shortcut for creating a new Document that is automatically saved to the db if valid.
show codeModel.create = function create (doc, fn) { var promise = new Promise , args if (Array.isArray(doc)) { args = doc; if ('function' == typeof fn) { promise.onResolve(fn); } } else { var last = arguments[arguments.length - 1]; if ('function' == typeof last) { promise.onResolve(last); args = utils.args(arguments, 0, arguments.length - 1); } else { args = utils.args(arguments); } } var count = args.length; if (0 === count) { promise.complete(); return promise; } var self = this; var docs = []; args.forEach(function (arg, i) { var doc = new self(arg); docs[i] = doc; doc.save(function (err) { if (err) return promise.error(err); --count || promise.complete.apply(promise, docs); }); }); return promise; };
Returns:
- <Promise>
Example:
// pass individual docs Candy.create({ type: 'jelly bean' }, { type: 'snickers' }, function (err, jellybean, snickers) { if (err) // ... }); // pass an array var array = [{ type: 'jelly bean' }, { type: 'snickers' }]; Candy.create(array, function (err, jellybean, snickers) { if (err) // ... }); // callback is optional; use the returned promise if you like: var promise = Candy.create({ type: 'jawbreaker' }); promise.then(function (jawbreaker) { // ... })
Model.discriminator(
name
,schema
)Adds a discriminator type.
show codeModel.discriminator = function discriminator (name, schema) { if (!(schema instanceof Schema)) { throw new Error("You must pass a valid discriminator Schema"); } if (this.schema.discriminatorMapping && !this.schema.discriminatorMapping.isRoot) { throw new Error("Discriminator \"" + name + "\" can only be a discriminator of the root model"); } var key = this.schema.options.discriminatorKey; if (schema.path(key)) { throw new Error("Discriminator \"" + name + "\" cannot have field with name \"" + key + "\""); } // merges base schema into new discriminator schema and sets new type field. (function mergeSchemas(schema, baseSchema) { utils.merge(schema, baseSchema); var obj = {}; obj[key] = { type: String, default: name }; schema.add(obj); schema.discriminatorMapping = { key: key, value: name, isRoot: false }; if (baseSchema.options.collection) { schema.options.collection = baseSchema.options.collection; } // throws error if options are invalid (function validateOptions(a, b) { a = utils.clone(a); b = utils.clone(b); delete a.toJSON; delete a.toObject; delete b.toJSON; delete b.toObject; if (!utils.deepEqual(a, b)) { throw new Error("Discriminator options are not customizable (except toJSON & toObject)"); } })(schema.options, baseSchema.options); var toJSON = schema.options.toJSON , toObject = schema.options.toObject; schema.options = utils.clone(baseSchema.options); if (toJSON) schema.options.toJSON = toJSON; if (toObject) schema.options.toObject = toObject; schema.callQueue = baseSchema.callQueue.concat(schema.callQueue); schema._requiredpaths = undefined; // reset just in case Schema#requiredPaths() was called on either schema })(schema, this.schema); if (!this.discriminators) { this.discriminators = {}; } if (!this.schema.discriminatorMapping) { this.schema.discriminatorMapping = { key: key, value: null, isRoot: true }; } if (this.discriminators[name]) { throw new Error("Discriminator with name \"" + name + "\" already exists"); } this.discriminators[name] = this.db.model(name, schema, this.collection.name); this.discriminators[name].prototype.__proto__ = this.prototype; return this.discriminators[name]; }; // Model (class) features
Example:
function BaseSchema() { Schema.apply(this, arguments); this.add({ name: String, createdAt: Date }); } util.inherits(BaseSchema, Schema); var PersonSchema = new BaseSchema(); var BossSchema = new BaseSchema({ department: String }); var Person = mongoose.model('Person', PersonSchema); var Boss = Person.discriminator('Boss', BossSchema);
Model.distinct(
field
,[conditions]
,[callback]
)Creates a Query for a
show codedistinct
operation.Model.distinct = function distinct (field, conditions, callback) { // get the mongodb collection object var mq = new Query({}, {}, this, this.collection); if ('function' == typeof conditions) { callback = conditions; conditions = {}; } return mq.distinct(conditions, field, callback); };
Returns:
- <Query>
Passing a
callback
immediately executes the query.Example
Link.distinct('url', { clicks: {$gt: 100}}, function (err, result) { if (err) return handleError(err); assert(Array.isArray(result)); console.log('unique urls with more than 100 clicks', result); }) var query = Link.distinct('url'); query.exec(callback);
Model.ensureIndexes(
[cb]
)Sends
show codeensureIndex
commands to mongo for each index declared in the schema.Model.ensureIndexes = function ensureIndexes (cb) { var promise = new Promise(cb); var indexes = this.schema.indexes(); if (!indexes.length) { process.nextTick(promise.fulfill.bind(promise)); return promise; } // Indexes are created one-by-one to support how MongoDB < 2.4 deals // with background indexes. var self = this , safe = self.schema.options.safe function done (err) { self.emit('index', err); promise.resolve(err); } function create () { var index = indexes.shift(); if (!index) return done(); var options = index[1]; options.safe = safe; self.collection.ensureIndex(index[0], options, tick(function (err) { if (err) return done(err); create(); })); } create(); return promise; }
Parameters:
[cb]
<Function> optional callback
Returns:
- <Promise>
Example:
Event.ensureIndexes(function (err) { if (err) return handleError(err); });
After completion, an
index
event is emitted on thisModel
passing an error if one occurred.Example:
var eventSchema = new Schema({ thing: { type: 'string', unique: true }}) var Event = mongoose.model('Event', eventSchema); Event.on('index', function (err) { if (err) console.error(err); // error occurred during index creation })
NOTE: It is not recommended that you run this in production. Index creation may impact database performance depending on your load. Use with caution.
The
ensureIndex
commands are not sent in parallel. This is to avoid theMongoError: cannot add index with a background operation in progress
error. See this ticket for more information.Model.find(
conditions
,[fields]
,[options]
,[callback]
)Finds documents
show codeModel.find = function find (conditions, fields, options, callback) { if ('function' == typeof conditions) { callback = conditions; conditions = {}; fields = null; options = null; } else if ('function' == typeof fields) { callback = fields; fields = null; options = null; } else if ('function' == typeof options) { callback = options; options = null; } // get the raw mongodb collection object var mq = new Query({}, options, this, this.collection); mq.select(fields); return mq.find(conditions, callback); };
Parameters:
Returns:
- <Query>
The
conditions
are cast to their respective SchemaTypes before the command is sent.Examples:
// named john and at least 18 MyModel.find({ name: 'john', age: { $gte: 18 }}); // executes immediately, passing results to callback MyModel.find({ name: 'john', age: { $gte: 18 }}, function (err, docs) {}); // name LIKE john and only selecting the "name" and "friends" fields, executing immediately MyModel.find({ name: /john/i }, 'name friends', function (err, docs) { }) // passing options MyModel.find({ name: /john/i }, null, { skip: 10 }) // passing options and executing immediately MyModel.find({ name: /john/i }, null, { skip: 10 }, function (err, docs) {}); // executing a query explicitly var query = MyModel.find({ name: /john/i }, null, { skip: 10 }) query.exec(function (err, docs) {}); // using the promise returned from executing a query var query = MyModel.find({ name: /john/i }, null, { skip: 10 }); var promise = query.exec(); promise.addBack(function (err, docs) {});
Model.findById(
id
,[fields]
,[options]
,[callback]
)Finds a single document by id.
show codeModel.findById = function findById (id, fields, options, callback) { return this.findOne({ _id: id }, fields, options, callback); };
Parameters:
Returns:
- <Query>
The
id
is cast based on the Schema before sending the command.Example:
// find adventure by id and execute immediately Adventure.findById(id, function (err, adventure) {}); // same as above Adventure.findById(id).exec(callback); // select only the adventures name and length Adventure.findById(id, 'name length', function (err, adventure) {}); // same as above Adventure.findById(id, 'name length').exec(callback); // include all properties except for `length` Adventure.findById(id, '-length').exec(function (err, adventure) {}); // passing options (in this case return the raw js objects, not mongoose documents by passing `lean` Adventure.findById(id, 'name', { lean: true }, function (err, doc) {}); // same as above Adventure.findById(id, 'name').lean().exec(function (err, doc) {});
Model.findByIdAndRemove(
id
,[options]
,[callback]
)Issue a mongodb findAndModify remove command by a documents id.
show codeModel.findByIdAndRemove = function (id, options, callback) { if (1 === arguments.length && 'function' == typeof id) { var msg = 'Model.findByIdAndRemove(): First argument must not be a function. ' + ' ' + this.modelName + '.findByIdAndRemove(id, callback) ' + ' ' + this.modelName + '.findByIdAndRemove(id) ' + ' ' + this.modelName + '.findByIdAndRemove() '; throw new TypeError(msg) } return this.findOneAndRemove({ _id: id }, options, callback); }
Parameters:
Returns:
- <Query>
Finds a matching document, removes it, passing the found document (if any) to the callback.
Executes immediately if
callback
is passed, else aQuery
object is returned.Options:
sort
: if multiple docs are found by the conditions, sets the sort order to choose which doc to updateselect
: sets the document fields to return
Examples:
A.findByIdAndRemove(id, options, callback) // executes A.findByIdAndRemove(id, options) // return Query A.findByIdAndRemove(id, callback) // executes A.findByIdAndRemove(id) // returns Query A.findByIdAndRemove() // returns Query
Model.findByIdAndUpdate(
id
,[update]
,[options]
,[callback]
)Issues a mongodb findAndModify update command by a documents id.
show codeModel.findByIdAndUpdate = function (id, update, options, callback) { var args; if (1 === arguments.length) { if ('function' == typeof id) { var msg = 'Model.findByIdAndUpdate(): First argument must not be a function. ' + ' ' + this.modelName + '.findByIdAndUpdate(id, callback) ' + ' ' + this.modelName + '.findByIdAndUpdate(id) ' + ' ' + this.modelName + '.findByIdAndUpdate() '; throw new TypeError(msg) } return this.findOneAndUpdate({_id: id }, undefined); } args = utils.args(arguments, 1); // if a model is passed in instead of an id if (id && id._id) { id = id._id; } if (id) { args.unshift({ _id: id }); } return this.findOneAndUpdate.apply(this, args); }
Parameters:
Returns:
- <Query>
Finds a matching document, updates it according to the
update
arg, passing anyoptions
, and returns the found document (if any) to the callback. The query executes immediately ifcallback
is passed else a Query object is returned.Options:
new
: bool - true to return the modified document rather than the original. defaults to trueupsert
: bool - creates the object if it doesn't exist. defaults to false.sort
: if multiple docs are found by the conditions, sets the sort order to choose which doc to updateselect
: sets the document fields to return
Examples:
A.findByIdAndUpdate(id, update, options, callback) // executes A.findByIdAndUpdate(id, update, options) // returns Query A.findByIdAndUpdate(id, update, callback) // executes A.findByIdAndUpdate(id, update) // returns Query A.findByIdAndUpdate() // returns Query
Finds a matching document, updates it according to the
update
arg, passing anyoptions
, and returns the found document (if any) to the callback. The query executes immediately ifcallback
is passed else a Query object is returned.Options:
new
: bool - true to return the modified document rather than the original. defaults to trueupsert
: bool - creates the object if it doesn't exist. defaults to false.sort
: if multiple docs are found by the conditions, sets the sort order to choose which doc to update
Note:
All top level update keys which are not
atomic
operation names are treated as set operations:Example:
Model.findByIdAndUpdate(id, { name: 'jason borne' }, options, callback) // is sent as Model.findByIdAndUpdate(id, { $set: { name: 'jason borne' }}, options, callback)
This helps prevent accidentally overwriting your document with
{ name: 'jason borne' }
.Note:
Although values are cast to their appropriate types when using the findAndModify helpers, the following are not applied:
- defaults
- setters
- validators
- middleware
If you need those features, use the traditional approach of first retrieving the document.
Model.findById(id, function (err, doc) { if (err) .. doc.name = 'jason borne'; doc.save(callback); })
Model.findOne(
conditions
,[fields]
,[options]
,[callback]
)Finds one document.
show codeModel.findOne = function findOne (conditions, fields, options, callback) { if ('function' == typeof options) { callback = options; options = null; } else if ('function' == typeof fields) { callback = fields; fields = null; options = null; } else if ('function' == typeof conditions) { callback = conditions; conditions = {}; fields = null; options = null; } // get the mongodb collection object var mq = new Query({}, options, this, this.collection); mq.select(fields); return mq.findOne(conditions, callback); };
Parameters:
Returns:
- <Query>
The
conditions
are cast to their respective SchemaTypes before the command is sent.Example:
// find one iphone adventures - iphone adventures?? Adventure.findOne({ type: 'iphone' }, function (err, adventure) {}); // same as above Adventure.findOne({ type: 'iphone' }).exec(function (err, adventure) {}); // select only the adventures name Adventure.findOne({ type: 'iphone' }, 'name', function (err, adventure) {}); // same as above Adventure.findOne({ type: 'iphone' }, 'name').exec(function (err, adventure) {}); // specify options, in this case lean Adventure.findOne({ type: 'iphone' }, 'name', { lean: true }, callback); // same as above Adventure.findOne({ type: 'iphone' }, 'name', { lean: true }).exec(callback); // chaining findOne queries (same as above) Adventure.findOne({ type: 'iphone' }).select('name').lean().exec(callback);
Model.findOneAndRemove(
conditions
,[options]
,[callback]
)Issue a mongodb findAndModify remove command.
show codeModel.findOneAndRemove = function (conditions, options, callback) { if (1 === arguments.length && 'function' == typeof conditions) { var msg = 'Model.findOneAndRemove(): First argument must not be a function. ' + ' ' + this.modelName + '.findOneAndRemove(conditions, callback) ' + ' ' + this.modelName + '.findOneAndRemove(conditions) ' + ' ' + this.modelName + '.findOneAndRemove() '; throw new TypeError(msg) } if ('function' == typeof options) { callback = options; options = undefined; } var fields; if (options) { fields = options.select; options.select = undefined; } var mq = new Query({}, {}, this, this.collection); mq.select(fields); return mq.findOneAndRemove(conditions, options, callback); }
Returns:
- <Query>
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.Options:
sort
: if multiple docs are found by the conditions, sets the sort order to choose which doc to updateselect
: sets the document fields to return
Examples:
A.findOneAndRemove(conditions, options, callback) // executes A.findOneAndRemove(conditions, options) // return Query A.findOneAndRemove(conditions, callback) // executes A.findOneAndRemove(conditions) // returns Query A.findOneAndRemove() // returns Query
Although values are cast to their appropriate types when using the findAndModify helpers, the following are not applied:
- defaults
- setters
- validators
- middleware
If you need those features, use the traditional approach of first retrieving the document.
Model.findById(id, function (err, doc) { if (err) .. doc.remove(callback); })
Model.findOneAndUpdate(
[conditions]
,[update]
,[options]
,[callback]
)Issues a mongodb findAndModify update command.
show codeModel.findOneAndUpdate = function (conditions, update, options, callback) { if ('function' == typeof options) { callback = options; options = null; } else if (1 === arguments.length) { if ('function' == typeof conditions) { var msg = 'Model.findOneAndUpdate(): First argument must not be a function. ' + ' ' + this.modelName + '.findOneAndUpdate(conditions, update, options, callback) ' + ' ' + this.modelName + '.findOneAndUpdate(conditions, update, options) ' + ' ' + this.modelName + '.findOneAndUpdate(conditions, update) ' + ' ' + this.modelName + '.findOneAndUpdate(update) ' + ' ' + this.modelName + '.findOneAndUpdate() '; throw new TypeError(msg) } update = conditions; conditions = undefined; } var fields; if (options && options.fields) { fields = options.fields; options.fields = undefined; } var mq = new Query({}, {}, this, this.collection); mq.select(fields); return mq.findOneAndUpdate(conditions, update, options, callback); }
Returns:
- <Query>
See:
Finds a matching document, updates it according to the
update
arg, passing anyoptions
, and returns the found document (if any) to the callback. The query executes immediately ifcallback
is passed else a Query object is returned.Options:
new
: bool - true to return the modified document rather than the original. defaults to trueupsert
: bool - creates the object if it doesn't exist. defaults to false.sort
: if multiple docs are found by the conditions, sets the sort order to choose which doc to updateselect
: sets the document fields to return
Examples:
A.findOneAndUpdate(conditions, update, options, callback) // executes A.findOneAndUpdate(conditions, update, options) // returns Query A.findOneAndUpdate(conditions, update, callback) // executes A.findOneAndUpdate(conditions, update) // returns Query A.findOneAndUpdate() // returns Query
Note:
All top level update keys which are not
atomic
operation names are treated as set operations:Example:
var query = { name: 'borne' }; Model.findOneAndUpdate(query, { name: 'jason borne' }, options, callback) // is sent as Model.findOneAndUpdate(query, { $set: { name: 'jason borne' }}, options, callback)
This helps prevent accidentally overwriting your document with
{ name: 'jason borne' }
.Note:
Although values are cast to their appropriate types when using the findAndModify helpers, the following are not applied:
- defaults
- setters
- validators
- middleware
If you need those features, use the traditional approach of first retrieving the document.
Model.findOne({ name: 'borne' }, function (err, doc) { if (err) .. doc.name = 'jason borne'; doc.save(callback); })
Model.geoNear(
GeoJSON
,options
,[callback]
)geoNear support for Mongoose
show codeModel.geoNear = function (near, options, callback) { if ('function' == typeof options) { callback = options; options = {}; } var promise = new Promise(callback); if (!near) { promise.error(new Error("Must pass a near option to geoNear")); return promise; } var x,y; if (Array.isArray(near)) { if (near.length != 2) { promise.error(new Error("If using legacy coordinates, must be an array of size 2 for geoNear")); return promise; } x = near[0]; y = near[1]; } else { if (near.type != "Point" || !Array.isArray(near.coordinates)) { promise.error(new Error("Must pass either a legacy coordinate array or GeoJSON Point to geoNear")); return promise; } x = near.coordinates[0]; y = near.coordinates[1]; } var self = this; this.collection.geoNear(x, y, options, function (err, res) { if (err) return promise.error(err); if (options.lean) return promise.fulfill(res.results, res.stats); var count = res.results.length; // if there are no results, fulfill the promise now if (count == 0) { return promise.fulfill(res.results, res.stats); } var errSeen = false; for (var i=0; i < res.results.length; i++) { var temp = res.results[i].obj; res.results[i].obj = new self(); res.results[i].obj.init(temp, function (err) { if (err && !errSeen) { errSeen = true; return promise.error(err); } --count || promise.fulfill(res.results, res.stats); }); } }); return promise; };
Parameters:
See:
Options:
lean
{Boolean} return the raw object- All options supported by the driver are also supported
Example:
// Legacy point Model.geoNear([1,3], { maxDistance : 5, spherical : true }, function(err, results, stats) { console.log(results); }); // geoJson var point = { type : "Point", coordinates : [9,9] }; Model.geoNear(point, { maxDistance : 5, spherical : true }, function(err, results, stats) { console.log(results); });
Model.geoSearch(
condition
,options
,[callback]
)Implements
show code$geoSearch
functionality for MongooseModel.geoSearch = function (conditions, options, callback) { if ('function' == typeof options) { callback = options; options = {}; } var promise = new Promise(callback); if (conditions == undefined || !utils.isObject(conditions)) { return promise.error(new Error("Must pass conditions to geoSearch")); } if (!options.near) { return promise.error(new Error("Must specify the near option in geoSearch")); } if (!Array.isArray(options.near)) { return promise.error(new Error("near option must be an array [x, y]")); } // send the conditions in the options object options.search = conditions; var self = this; this.collection.geoHaystackSearch(options.near[0], options.near[1], options, function (err, res) { // have to deal with driver problem. Should be fixed in a soon-ish release // (7/8/2013) if (err || res.errmsg) { if (!err) err = new Error(res.errmsg); if (res && res.code !== undefined) err.code = res.code; return promise.error(err); } if (options.lean) return promise.fulfill(res.results, res.stats); var count = res.results.length; var errSeen = false; for (var i=0; i < res.results.length; i++) { var temp = res.results[i]; res.results[i] = new self(); res.results[i].init(temp, {}, function (err) { if (err && !errSeen) { errSeen = true; return promise.error(err); } --count || (!errSeen && promise.fulfill(res.results, res.stats)); }); } }); return promise; };
Parameters:
See:
Example:
var options = { near: [10, 10], maxDistance: 5 }; Locations.geoSearch({ type : "house" }, options, function(err, res) { console.log(res); });
Options:
near
{Array} x,y point to search formaxDistance
{Number} the maximum distance from the point near that a result can belimit
{Number} The maximum number of results to returnlean
{Boolean} return the raw object instead of the Mongoose Model
Model.init()
Called when the model compiles.
show codeModel.init = function init () { if (this.schema.options.autoIndex) { this.ensureIndexes(); } this.schema.emit('init', this); };
Model.mapReduce(
o
,[callback]
)Executes a mapReduce command.
show codeModel.mapReduce = function mapReduce (o, callback) { var promise = new Promise(callback); var self = this; if (!Model.mapReduce.schema) { var opts = { noId: true, noVirtualId: true, strict: false } Model.mapReduce.schema = new Schema({}, opts); } if (!o.out) o.out = { inline: 1 }; o.map = String(o.map); o.reduce = String(o.reduce); if (o.query) { var q = new Query(o.query); q.cast(this); o.query = q._conditions; q = undefined; } this.collection.mapReduce(null, null, o, function (err, ret, stats) { if (err) return promise.error(err); if (ret.findOne && ret.mapReduce) { // returned a collection, convert to Model var model = Model.compile( '_mapreduce_' + ret.collectionName , Model.mapReduce.schema , ret.collectionName , self.db , self.base); model._mapreduce = true; return promise.fulfill(model, stats); } promise.fulfill(ret, stats); }); return promise; }
Parameters:
Returns:
- <Promise>
o
is an object specifying all mapReduce options as well as the map and reduce functions. All options are delegated to the driver implementation.Example:
var o = {}; o.map = function () { emit(this.name, 1) } o.reduce = function (k, vals) { return vals.length } User.mapReduce(o, function (err, results) { console.log(results) })
Other options:
query
{Object} query filter object.limit
{Number} max number of documentskeeptemp
{Boolean, default:false} keep temporary datafinalize
{Function} finalize functionscope
{Object} scope variables exposed to map/reduce/finalize during executionjsMode
{Boolean, default:false} it is possible to make the execution stay in JS. Provided in MongoDB > 2.0.Xverbose
{Boolean, default:false} provide statistics on job execution time.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 toreplace
,merge
, orreduce
, a Model instance is returned that can be used for further querying. Queries run against this model are all executed with thelean
option; meaning only the js object is returned and no Mongoose magic is applied (getters, setters, etc).Example:
var o = {}; o.map = function () { emit(this.name, 1) } o.reduce = function (k, vals) { return vals.length } o.out = { replace: 'createdCollectionNameForResults' } o.verbose = true; User.mapReduce(o, function (err, model, stats) { console.log('map reduce took %d ms', stats.processtime) model.find().where('value').gt(10).exec(function (err, docs) { console.log(docs); }); }) // a promise is returned so you may instead write var promise = User.mapReduce(o); promise.then(function (model, stats) { console.log('map reduce took %d ms', stats.processtime) return model.find().where('value').gt(10).exec(); }).then(function (docs) { console.log(docs); }).then(null, handleError).end()
Model.populate(
docs
,options
,[cb(err,doc)]
)Populates document references.
show codeModel.populate = function (docs, paths, cb) { var promise = new Promise(cb); // always resolve on nextTick for consistent async behavior function resolve () { var args = utils.args(arguments); process.nextTick(function () { promise.resolve.apply(promise, args); }); } // normalized paths var paths = utils.populate(paths); var pending = paths.length; if (0 === pending) { resolve(null, docs); return promise; } // each path has its own query options and must be executed separately var i = pending; var path; while (i--) { path = paths[i]; populate(this, docs, path, next); } return promise; function next (err) { if (err) return resolve(err); if (--pending) return; resolve(null, docs); } }
Parameters:
Returns:
- <Promise>
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:
// populates a single object User.findById(id, function (err, user) { var opts = [ { path: 'company', match: { x: 1 }, select: 'name' } , { path: 'notes', options: { limit: 10 }, model: 'override' } ] User.populate(user, opts, function (err, user) { console.log(user); }) }) // populates an array of objects User.find(match, function (err, users) { var opts = [{ path: 'company', match: { x: 1 }, select: 'name' }] var promise = User.populate(users, opts); promise.then(console.log).end(); }) // imagine a Weapon model exists with two saved documents: // { _id: 389, name: 'whip' } // { _id: 8921, name: 'boomerang' } var user = { name: 'Indiana Jones', weapon: 389 } Weapon.populate(user, { path: 'weapon', model: 'Weapon' }, function (err, user) { console.log(user.weapon.name) // whip }) // populate many plain objects var users = [{ name: 'Indiana Jones', weapon: 389 }] users.push({ name: 'Batman', weapon: 8921 }) Weapon.populate(users, { path: 'weapon' }, function (err, users) { users.forEach(function (user) { console.log('%s uses a %s', users.name, user.weapon.name) // Indiana Jones uses a whip // Batman uses a boomerang }) }) // Note that we didn't need to specify the Weapon model because // we were already using it's populate() method.
Model.remove(
conditions
,[callback]
)Removes documents from the collection.
show codeModel.remove = function remove (conditions, callback) { if ('function' === typeof conditions) { callback = conditions; conditions = {}; } // get the mongodb collection object var mq = new Query(conditions, {}, this, this.collection); return mq.remove(callback); };
Returns:
- <Query>
Example:
Comment.remove({ title: 'baby born from alien father' }, function (err) { });
Note:
To remove documents without waiting for a response from MongoDB, do not pass a
callback
, then callexec
on the returned Query:var query = Comment.remove({ _id: id }); query.exec();
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.update(
conditions
,update
,[options]
,[callback]
)Updates documents in the database without returning them.
show codeModel.update = function update (conditions, doc, options, callback) { var mq = new Query({}, {}, this, this.collection); return mq.update(conditions, doc, options, callback); };
Returns:
- <Query>
See:
Examples:
MyModel.update({ age: { $gt: 18 } }, { oldEnough: true }, fn); MyModel.update({ name: 'Tobi' }, { ferret: true }, { multi: true }, function (err, numberAffected, raw) { if (err) return handleError(err); console.log('The number of updated documents was %d', numberAffected); console.log('The raw response from Mongo was ', raw); });
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)strict
(boolean) overrides thestrict
option for this update
All
update
values are cast to their appropriate SchemaTypes before being sent.The
callback
function receives(err, numberAffected, rawResponse)
.err
is the error if any occurrednumberAffected
is the count of updated documents Mongo reportedrawResponse
is the full response from Mongo
Note:
All top level keys which are not
atomic
operation names are treated as set operations:Example:
var query = { name: 'borne' }; Model.update(query, { name: 'jason borne' }, options, callback) // is sent as Model.update(query, { $set: { name: 'jason borne' }}, options, callback)
This helps prevent accidentally overwriting all documents in your collection with
{ name: 'jason borne' }
.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 callexec
on the returned Query: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.
Model.findOne({ name: 'borne' }, function (err, doc) { if (err) .. doc.name = 'jason borne'; doc.save(callback); })
Model.where(
path
,[val]
)Creates a Query, applies the passed conditions, and returns the Query.
show codeModel.where = function where (path, val) { // get the mongodb collection object var mq = new Query({}, {}, this, this.collection).find({}); return mq.where.apply(mq, arguments); };
Returns:
- <Query>
For example, instead of writing:
User.find({age: {$gte: 21, $lte: 65}}, callback);
we can instead write:
User.where('age').gte(21).lte(65).exec(callback);
Since the Query class also supports
where
you can continue chainingUser .where('age').gte(21).lte(65) .where('name', /^b/i) ... etc
- promise.js
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 rejectedcomplete
: Emits when the promise is fulfilled
show codePromises are returned from executed queries. Example:
var query = Candy.find({ bar: true }); var promise = query.exec();
function Promise (fn) { MPromise.call(this, fn); }
Promise#addBack(
listener
)Adds a single function as a listener to both err and complete.
Parameters:
listener
<Function>
Returns:
- <Promise> this
It will be executed with traditional node.js argument position when the promise is resolved.
promise.addBack(function (err, args...) { if (err) return handleError(err); console.log('success'); })
Alias of mpromise#onResolve.
Deprecated. Use
onResolve
instead.Promise#addCallback(
listener
)Adds a listener to the
complete
(success) event.Parameters:
listener
<Function>
Returns:
- <Promise> this
Alias of mpromise#onFulfill.
Deprecated. Use
onFulfill
instead.Promise#addErrback(
listener
)Adds a listener to the
err
(rejected) event.Parameters:
listener
<Function>
Returns:
- <Promise> this
Alias of mpromise#onReject.
Deprecated. Use
onReject
instead.Promise#complete(
args
)Fulfills this promise with passed arguments.
Parameters:
args
<T>
Alias of mpromise#fulfill.
Deprecated. Use
fulfill
instead.Promise#end()
Signifies that this promise was the last in a chain of
then()s
: if a handler passed to the call tothen
which produced this promise throws, the exception will go uncaught.See:
Example:
var p = new Promise; p.then(function(){ throw new Error('shucks') }); setTimeout(function () { p.fulfill(); // error was caught and swallowed by the promise returned from // p.then(). we either have to always register handlers on // the returned promises or we can do the following... }, 10); // this time we use .end() which prevents catching thrown errors var p = new Promise; var p2 = p.then(function(){ throw new Error('shucks') }).end(); // <-- setTimeout(function () { p.fulfill(); // throws "shucks" }, 10);
Promise#error(
err
)Rejects this promise with
err
.Returns:
- <Promise> this
show codeIf the promise has already been fulfilled or rejected, not action is taken.
Differs from #reject by first casting
err
to anError
if it is notinstanceof Error
.Promise.prototype.error = function (err) { if (!(err instanceof Error)) err = new Error(err); return this.reject(err); }
function Object() { [native code] }#fulfill(
args
)Fulfills this promise with passed arguments.
Parameters:
args
<T>
function Object() { [native code] }#fulfill(
args
)Fulfills this promise with passed arguments.
Parameters:
args
<T>
Promise#on(
event
,listener
)Adds
listener
to theevent
.Returns:
- <Promise> this
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#reject(
reason
)Rejects this promise with
reason
.Returns:
- <Promise> this
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 noerr
is passed.show codeIf 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.
Promise.prototype.resolve = function (err, val) { if (err) return this.error(err); return this.fulfill(val); }
Promise#then(
onFulFill
,onReject
)Creates a new promise and returns it. If
onFulfill
oronReject
are passed, they are added as SUCCESS/ERROR callbacks to this promise after the nextTick.Returns:
- <Promise> newPromise
Conforms to promises/A+ specification.
Example:
var promise = Meetups.find({ tags: 'javascript' }).select('_id').exec(); promise.then(function (meetups) { var ids = meetups.map(function (m) { return m._id; }); return People.find({ meetups: { $in: ids }).exec(); }).then(function (people) { if (people.length < 10000) { throw new Error('Too few people!!!'); } else { throw new Error('Still need more people!!!'); } }).then(null, function (err) { assert.ok(err instanceof Error); });
- query.js
Query#$where(
js
)Specifies a javascript function or expression to pass to MongoDBs query system.
Returns:
- <Query> this
See:
Example
query.$where('this.comments.length > 10 || this.name.length > 5') // or query.$where(function () { return this.comments.length > 10 || this.name.length > 5; })
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(
[options]
,[model]
,[conditions]
,[collection]
)Query constructor used for building queries.
Parameters:
show codeExample:
var query = new Query(); query.setOptions({ lean : true }); query.collection(model.collection); query.where('age').gte(21).exec(callback);
function Query(conditions, options, model, collection) { // this stuff is for dealing with custom queries created by #toConstructor if (!this._mongooseOptions) { this._mongooseOptions = options || {}; } else { // this is the case where we have a CustomQuery, we need to check if we got // options passed in, and if we did, merge them in if (options) { var keys = Object.keys(options); for (var i=0; i < keys.length; i++) { var k = keys[i]; this._mongooseOptions[k] = options[k]; } } } if (collection) { this.mongooseCollection = collection; } if (model) { this.model = model; } // this is needed because map reduce returns a model that can be queried, but // all of the queries on said model should be lean if (this.model && this.model._mapreduce) { this.lean(); } // inherit mquery mquery.call(this, this.mongooseCollection, options); if (conditions) { this.find(conditions); } }
Query#_applyPaths()
Applies schematype selected options to this query.
show codeQuery.prototype._applyPaths = function applyPaths () { // determine if query is selecting or excluding fields var fields = this._fields , exclude , keys , ki if (fields) { keys = Object.keys(fields); ki = keys.length; while (ki--) { if ('+' == keys[ki][0]) continue; exclude = 0 === fields[keys[ki]]; break; } } // if selecting, apply default schematype select:true fields // if excluding, apply schematype select:false fields var selected = [] , excluded = [] , seen = []; analyzeSchema(this.model.schema); switch (exclude) { case true: excluded.length && this.select('-' + excluded.join(' -')); break; case false: selected.length && this.select(selected.join(' ')); break; case undefined: // user didn't specify fields, implies returning all fields. // only need to apply excluded fields excluded.length && this.select('-' + excluded.join(' -')); break; } return seen = excluded = selected = keys = fields = null; function analyzeSchema (schema, prefix) { prefix || (prefix = ''); // avoid recursion if (~seen.indexOf(schema)) return; seen.push(schema); schema.eachPath(function (path, type) { if (prefix) path = prefix + '.' + path; analyzePath(path, type); // array of subdocs? if (type.schema) { analyzeSchema(type.schema, path); } }); } function analyzePath (path, type) { if ('boolean' != typeof type.selected) return; var plusPath = '+' + path; if (fields && plusPath in fields) { // forced inclusion delete fields[plusPath]; // if there are other fields being included, add this one // if no other included fields, leave this out (implied inclusion) if (false === exclude && keys.length > 1 && !~keys.indexOf(path)) { fields[path] = 1; } return }; // check for parent exclusions var root = path.split('.')[0]; if (~excluded.indexOf(root)) return; ;(type.selected ? selected : excluded).push(path); } }
Query#_castFields(
fields
)Casts selected field arguments for field selection with mongo 2.2
Parameters:
fields
<Object>
See:
show codequery.select({ ids: { $elemMatch: { $in: [hexString] }})
Query.prototype._castFields = function _castFields (fields) { var selected , elemMatchKeys , keys , key , out , i if (fields) { keys = Object.keys(fields); elemMatchKeys = []; i = keys.length; // collect $elemMatch args while (i--) { key = keys[i]; if (fields[key].$elemMatch) { selected || (selected = {}); selected[key] = fields[key]; elemMatchKeys.push(key); } } } if (selected) { // they passed $elemMatch, cast em try { out = this.cast(this.model, selected); } catch (err) { return err; } // apply the casted field args i = elemMatchKeys.length; while (i--) { key = elemMatchKeys[i]; fields[key] = out[key]; } } return fields; }
Query#_castFields(
fields
)Casts selected field arguments for field selection with mongo 2.2
Parameters:
fields
<Object>
See:
show codequery.select({ ids: { $elemMatch: { $in: [hexString] }})
Query.prototype._castFields = function _castFields (fields) { var selected , elemMatchKeys , keys , key , out , i if (fields) { keys = Object.keys(fields); elemMatchKeys = []; i = keys.length; // collect $elemMatch args while (i--) { key = keys[i]; if (fields[key].$elemMatch) { selected || (selected = {}); selected[key] = fields[key]; elemMatchKeys.push(key); } } } if (selected) { // they passed $elemMatch, cast em try { out = this.cast(this.model, selected); } catch (err) { return err; } // apply the casted field args i = elemMatchKeys.length; while (i--) { key = elemMatchKeys[i]; fields[key] = out[key]; } } return fields; }
Query#_castUpdate(
obj
)Casts obj for an update command.
Parameters:
obj
<Object>
show codeReturns:
- <Object> obj after casting its values
Query.prototype._castUpdate = function _castUpdate (obj, overwrite) { if (!obj) return undefined; var ops = Object.keys(obj) , i = ops.length , ret = {} , hasKeys , val while (i--) { var op = ops[i]; // if overwrite is set, don't do any of the special $set stuff if ('$' !== op[0] && !overwrite) { // fix up $set sugar if (!ret.$set) { if (obj.$set) { ret.$set = obj.$set; } else { ret.$set = {}; } } ret.$set[op] = obj[op]; ops.splice(i, 1); if (!~ops.indexOf('$set')) ops.push('$set'); } else if ('$set' === op) { if (!ret.$set) { ret[op] = obj[op]; } } else { ret[op] = obj[op]; } } // cast each value i = ops.length; // if we get passed {} for the update, we still need to respect that when it // is an overwrite scenario if (overwrite) { hasKeys = true; } while (i--) { op = ops[i]; val = ret[op]; if ('Object' === val.constructor.name && !overwrite) { hasKeys |= this._walkUpdatePath(val, op); } else if (overwrite && 'Object' === ret.constructor.name) { // if we are just using overwrite, cast the query and then we will // *always* return the value, even if it is an empty object. We need to // set hasKeys above because we need to account for the case where the // user passes {} and wants to clobber the whole document // Also, _walkUpdatePath expects an operation, so give it $set since that // is basically what we're doing this._walkUpdatePath(ret, '$set'); } else { var msg = 'Invalid atomic update value for ' + op + '. ' + 'Expected an object, received ' + typeof val; throw new Error(msg); } } return hasKeys && ret; }
Query#_castUpdateVal(
schema
,val
,op
,[$conditional]
)Casts
val
according toschema
and atomicop
.show codeParameters:
Query.prototype._castUpdateVal = function _castUpdateVal (schema, val, op, $conditional) { if (!schema) { // non-existing schema path return op in numberOps ? Number(val) : val } if (schema.caster && op in castOps && (utils.isObject(val) || Array.isArray(val))) { // Cast values for ops that add data to MongoDB. // Ensures embedded documents get ObjectIds etc. var tmp = schema.cast(val); if (Array.isArray(val)) { val = tmp; } else { val = tmp[0]; } } if (op in numberOps) return Number(val); if (/^\$/.test($conditional)) return schema.castForQuery($conditional, val); return schema.castForQuery(val) }
function Object() { [native code] }#_ensurePath(
method
)Makes sure _path is set.
Parameters:
method
<String>
function Object() { [native code] }#_fieldsForExec()
Returns fields selection for this query.
Returns:
- <Object>
Query#_findAndModify(
type
,callback
)Override mquery.prototype._findAndModify to provide casting etc.
show codeQuery.prototype._findAndModify = function (type, callback) { if ('function' != typeof callback) { throw new Error("Expected callback in _findAndModify"); } var model = this.model , promise = new Promise(callback) , self = this , castedQuery , castedDoc , fields , opts; castedQuery = castQuery(this); if (castedQuery instanceof Error) { process.nextTick(promise.error.bind(promise, castedQuery)); return promise; } opts = this._optionsForExec(model); if ('remove' == type) { opts.remove = true; } else { if (!('new' in opts)) opts.new = true; if (!('upsert' in opts)) opts.upsert = false; castedDoc = castDoc(this); if (!castedDoc) { if (opts.upsert) { // still need to do the upsert to empty doc castedDoc = { $set: {} }; } else { return this.findOne(callback); } } else if (castedDoc instanceof Error) { process.nextTick(promise.error.bind(promise, castedDoc)); return promise; } } this._applyPaths(); var self = this; var options = this._mongooseOptions; if (this._fields) { fields = utils.clone(this._fields); opts.fields = this._castFields(fields); if (opts.fields instanceof Error) { process.nextTick(promise.error.bind(promise, opts.fields)); return promise; } } this._collection.findAndModify(castedQuery, castedDoc, opts, utils.tick(cb)); function cb (err, doc) { if (err) return promise.error(err); if (!doc || (utils.isObject(doc) && Object.keys(doc).length === 0)) { return promise.complete(null); } if (!options.populate) { return true === options.lean ? promise.complete(doc) : completeOne(self.model, doc, fields, self, null, promise); } var pop = helpers.preparePopulationOptionsMQ(self, options); self.model.populate(doc, pop, function (err, doc) { if (err) return promise.error(err); return true === options.lean ? promise.complete(doc) : completeOne(self.model, doc, fields, self, pop, promise); }); } return promise; }
Query#_getSchema(
path
)Finds the schema for
path
. This is different than
callingschema.path
as it also resolves paths with
positional selectors (something.$.another.$.path).show codeParameters:
path
<String>
Query.prototype._getSchema = function _getSchema (path) { return this.model._getSchema(path); }
Query#_optionsForExec(
model
)Returns default options for this query.
show codeParameters:
model
<Model>
Query.prototype._optionsForExec = function (model) { var options = Query.base._optionsForExec.call(this); delete options.populate; if (!model) { return options; } else { if (!('safe' in options) && model.schema.options.safe) { options.safe = model.schema.options.safe; } if(!('readPreference' in options) && model.schema.options.read) { options.readPreference = model.schema.options.read; } return options; } };
function Object() { [native code] }#_updateForExec()
Return an update document with corrected $set operations.
Query#_walkUpdatePath(
obj
,op
,pref
)Walk each path of obj and cast its values
according to its schema.Parameters:
show codeReturns:
- <Bool> true if this path has keys to update
Query.prototype._walkUpdatePath = function _walkUpdatePath (obj, op, pref) { var prefix = pref ? pref + '.' : '' , keys = Object.keys(obj) , i = keys.length , hasKeys = false , schema , key , val var strict = 'strict' in this._mongooseOptions ? this._mongooseOptions.strict : this.model.schema.options.strict; while (i--) { key = keys[i]; val = obj[key]; if (val && 'Object' === val.constructor.name) { // watch for embedded doc schemas schema = this._getSchema(prefix + key); if (schema && schema.caster && op in castOps) { // embedded doc schema if (strict && !schema) { // path is not in our strict schema if ('throw' == strict) { throw new Error('Field `' + key + '` is not in schema.'); } else { // ignore paths not specified in schema delete obj[key]; } } else { hasKeys = true; if ('$each' in val) { obj[key] = { $each: this._castUpdateVal(schema, val.$each, op) } if (val.$slice) { obj[key].$slice = val.$slice | 0; } if (val.$sort) { obj[key].$sort = val.$sort; } } else { obj[key] = this._castUpdateVal(schema, val, op); } } } else { hasKeys |= this._walkUpdatePath(val, op, prefix + key); } } else { schema = '$each' === key ? this._getSchema(pref) : this._getSchema(prefix + key); var skip = strict && !schema && !/real|nested/.test(this.model.schema.pathType(prefix + key)); if (skip) { if ('throw' == strict) { throw new Error('Field `' + prefix + key + '` is not in schema.'); } else { delete obj[key]; } } else { hasKeys = true; obj[key] = this._castUpdateVal(schema, val, op, key); } } } return hasKeys; }
Query#all(
[path]
,val
)Specifies an $all query condition.
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:
- <Query> this
See:
Example
query.and([{ color: 'green' }, { status: 'ok' }])
Query#batchSize(
val
)Specifies the batchSize option.
Parameters:
val
<Number>
See:
Example
query.batchSize(100)
Note
Cannot be used with
distinct()
Query#box(
val
,Upper
)Specifies a $box condition
Returns:
- <Query> this
Example
var lowerLeft = [40.73083, -73.99756] var upperRight= [40.741404, -73.988135] query.where('loc').within().box(lowerLeft, upperRight) query.box({ ll : lowerLeft, ur : upperRight })
Query#canMerge(
conds
)Determines if
conds
can be merged usingmquery().merge()
Parameters:
conds
<Object>
Returns:
- <Boolean>
Query#cast(
model
,[obj]
)Casts this query to the schema of
model
Returns:
- <Object>
show codeNote
If
obj
is present, it is cast instead of this query.Query.prototype.cast = function (model, obj) { obj || (obj = this._conditions); var schema = model.schema , paths = Object.keys(obj) , i = paths.length , any$conditionals , schematype , nested , path , type , val; while (i--) { path = paths[i]; val = obj[path]; if ('$or' === path || '$nor' === path || '$and' === path) { var k = val.length , orComponentQuery; while (k--) { orComponentQuery = new Query(val[k], {}, null, this.mongooseCollection); orComponentQuery.cast(model); val[k] = orComponentQuery._conditions; } } else if (path === '$where') { type = typeof val; if ('string' !== type && 'function' !== type) { throw new Error("Must have a string or function for $where"); } if ('function' === type) { obj[path] = val.toString(); } continue; } else { if (!schema) { // no casting for Mixed types continue; } schematype = schema.path(path); if (!schematype) { // Handle potential embedded array queries var split = path.split('.') , j = split.length , pathFirstHalf , pathLastHalf , remainingConds , castingQuery; // Find the part of the var path that is a path of the Schema while (j--) { pathFirstHalf = split.slice(0, j).join('.'); schematype = schema.path(pathFirstHalf); if (schematype) break; } // If a substring of the input path resolves to an actual real path... if (schematype) { // Apply the casting; similar code for $elemMatch in schema/array.js if (schematype.caster && schematype.caster.schema) { remainingConds = {}; pathLastHalf = split.slice(j).join('.'); remainingConds[pathLastHalf] = val; castingQuery = new Query(remainingConds, {}, null, this.mongooseCollection); castingQuery.cast(schematype.caster); obj[path] = castingQuery._conditions[pathLastHalf]; } else { obj[path] = val; } continue; } if (utils.isObject(val)) { // handle geo schemas that use object notation // { loc: { long: Number, lat: Number } var geo = val.$near ? '$near' : val.$nearSphere ? '$nearSphere' : val.$within ? '$within' : val.$geoIntersects ? '$geoIntersects' : ''; if (!geo) { continue; } var numbertype = new Types.Number('__QueryCasting__') var value = val[geo]; if (val.$maxDistance) { val.$maxDistance = numbertype.castForQuery(val.$maxDistance); } if ('$within' == geo) { var withinType = value.$center || value.$centerSphere || value.$box || value.$polygon; if (!withinType) { throw new Error('Bad $within paramater: ' + JSON.stringify(val)); } value = withinType; } else if ('$near' == geo && 'string' == typeof value.type && Array.isArray(value.coordinates)) { // geojson; cast the coordinates value = value.coordinates; } else if (('$near' == geo || '$geoIntersects' == geo) && value.$geometry && 'string' == typeof value.$geometry.type && Array.isArray(value.$geometry.coordinates)) { // geojson; cast the coordinates value = value.$geometry.coordinates; } ;(function _cast (val) { if (Array.isArray(val)) { val.forEach(function (item, i) { if (Array.isArray(item) || utils.isObject(item)) { return _cast(item); } val[i] = numbertype.castForQuery(item); }); } else { var nearKeys= Object.keys(val); var nearLen = nearKeys.length; while (nearLen--) { var nkey = nearKeys[nearLen]; var item = val[nkey]; if (Array.isArray(item) || utils.isObject(item)) { _cast(item); val[nkey] = item; } else { val[nkey] = numbertype.castForQuery(item); } } } })(value); } } else if (val === null || val === undefined) { continue; } else if ('Object' === val.constructor.name) { any$conditionals = Object.keys(val).some(function (k) { return k.charAt(0) === '$' && k !== '$id' && k !== '$ref'; }); if (!any$conditionals) { obj[path] = schematype.castForQuery(val); } else { var ks = Object.keys(val) , k = ks.length , $cond; while (k--) { $cond = ks[k]; nested = val[$cond]; if ('$exists' === $cond) { if ('boolean' !== typeof nested) { throw new Error("$exists parameter must be Boolean"); } continue; } if ('$type' === $cond) { if ('number' !== typeof nested) { throw new Error("$type parameter must be Number"); } continue; } if ('$not' === $cond) { this.cast(model, nested); } else { val[$cond] = schematype.castForQuery($cond, nested); } } } } else { obj[path] = schematype.castForQuery(val); } } } return obj; }
Query#centerSphere(
[path]
,val
)DEPRECATED Specifies a $centerSphere condition
Returns:
- <Query> this
show codeDeprecated. Use circle instead.
Example
var area = { center: [50, 50], radius: 10 }; query.where('loc').within().centerSphere(area);
Query.prototype.centerSphere = function () { if (arguments[0] && arguments[0].constructor.name == 'Object') { arguments[0].spherical = true; } if (arguments[1] && arguments[1].constructor.name == 'Object') { arguments[1].spherical = true; } Query.base.circle.apply(this, arguments); }
Query#circle(
[path]
,area
)Specifies a $center or $centerSphere condition.
Returns:
- <Query> this
Example
var area = { center: [50, 50], radius: 10, unique: true } query.where('loc').within().circle(area) // alternatively query.circle('loc', area); // spherical calculations var area = { center: [50, 50], radius: 10, unique: true, spherical: true } query.where('loc').within().circle(area) // alternatively query.circle('loc', area);
New in 3.7.0
Query#comment(
val
)Specifies the
comment
option.Parameters:
val
<Number>
See:
Example
query.comment('login query')
Note
Cannot be used with
distinct()
Query#count(
[criteria]
,[callback]
)Specifying this query as a
count
query.Returns:
- <Query> this
See:
show codePassing a
callback
executes the query.Example:
var countQuery = model.where({ 'color': 'black' }).count(); query.count({ color: 'black' }).count(callback) query.count({ color: 'black' }, callback) query.where('color', 'black').count(function (err, count) { if (err) return handleError(err); console.log('there are %d kittens', count); })
Query.prototype.count = function (conditions, callback) { if ('function' == typeof conditions) { callback = conditions; conditions = undefined; } if (mquery.canMerge(conditions)) { this.merge(conditions); } try { this.cast(this.model); } catch (err) { callback(err); return this; } return Query.base.count.call(this, {}, callback); }
Query#distinct(
[criteria]
,[field]
,[callback]
)Declares or executes a distict() operation.
Returns:
- <Query> this
See:
show codePassing a
callback
executes the query.Example
distinct(criteria, field, fn) distinct(criteria, field) distinct(field, fn) distinct(field) distinct(fn) distinct()
Query.prototype.distinct = function (conditions, field, callback) { if (!callback) { if('function' == typeof field) { callback = field; if ('string' == typeof conditions) { field = conditions; conditions = undefined; } } switch (typeof conditions) { case 'string': field = conditions; conditions = undefined; break; case 'function': callback = conditions; field = undefined; conditions = undefined; break; } } if (conditions instanceof Document) { conditions = conditions.toObject(); } if (mquery.canMerge(conditions)) { this.merge(conditions) } try { this.cast(this.model); } catch (err) { callback(err); return this; } return Query.base.distinct.call(this, {}, field, callback); }
Query#elemMatch(
path
,criteria
)Specifies an
$elemMatch
conditionReturns:
- <Query> this
See:
Example
query.elemMatch('comment', { author: 'autobot', votes: {$gte: 5}}) query.where('comment').elemMatch({ author: 'autobot', votes: {$gte: 5}}) query.elemMatch('comment', function (elem) { elem.where('author').equals('autobot'); elem.where('votes').gte(5); }) query.where('comment').elemMatch(function (elem) { elem.where({ author: 'autobot' }); elem.where('votes').gte(5); })
Query#equals(
val
)Specifies the complementary comparison value for paths specified with
where()
Parameters:
val
<Object>
Returns:
- <Query> this
Example
User.where('age').equals(49); // is the same as User.where('age', 49);
Query#exec(
[operation]
,[callback]
)Executes the query
Returns:
- <Promise>
show codeExamples:
var promise = query.exec(); var promise = query.exec('update'); query.exec(callback); query.exec('find', callback);
Query.prototype.exec = function exec (op, callback) { var promise = new Promise(); if ('function' == typeof op) { callback = op; op = null; } else if ('string' == typeof op) { this.op = op; } if (callback) promise.addBack(callback); if (!this.op) { promise.complete(); return promise; } Query.base.exec.call(this, op, promise.resolve.bind(promise)); return promise; }
Query#exists(
[path]
,val
)Specifies an
$exists
conditionReturns:
- <Query> this
See:
Example
// { name: { $exists: true }} Thing.where('name').exists() Thing.where('name').exists(true) Thing.find().exists('name') // { name: { $exists: false }} Thing.where('name').exists(false); Thing.find().exists('name', false);
Query#find(
[criteria]
,[callback]
)Finds documents.
Returns:
- <Query> this
show codeWhen no
callback
is passed, the query is not executed.Example
query.find({ name: 'Los Pollos Hermanos' }).find(callback)
Query.prototype.find = function (conditions, callback) { if ('function' == typeof conditions) { callback = conditions; conditions = {}; } else if (conditions instanceof Document) { conditions = conditions.toObject(); } if (mquery.canMerge(conditions)) { this.merge(conditions); } prepareDiscriminatorCriteria(this); try { this.cast(this.model); this._castError = null; } catch (err) { this._castError = err; } // if we don't have a callback, then just return the query object if (!callback) { return Query.base.find.call(this); } var promise = new Promise(callback); if (this._castError) { promise.error(this._castError); return this; } this._applyPaths(); this._fields = this._castFields(this._fields); var fields = this._fieldsForExec(); var options = this._mongooseOptions; var self = this; return Query.base.find.call(this, {}, cb); function cb(err, docs) { if (err) return promise.error(err); if (0 === docs.length) { return promise.complete(docs); } if (!options.populate) { return true === options.lean ? promise.complete(docs) : completeMany(self.model, docs, fields, self, null, promise); } var pop = helpers.preparePopulationOptionsMQ(self, options); self.model.populate(docs, pop, function (err, docs) { if(err) return promise.error(err); return true === options.lean ? promise.complete(docs) : completeMany(self.model, docs, fields, self, pop, promise); }); } }
Query#findOne(
[criteria]
,[callback]
)Declares the query a findOne operation. When executed, the first found document is passed to the callback.
Returns:
- <Query> this
See:
show codePassing a
callback
executes the query.Example
var query = Kitten.where({ color: 'white' }); query.findOne(function (err, kitten) { if (err) return handleError(err); if (kitten) { // doc may be null if no document matched } });
Query.prototype.findOne = function (conditions, fields, options, callback) { if ('function' == typeof conditions) { callback = conditions; conditions = null; fields = null; options = null; } if ('function' == typeof fields) { callback = fields; options = null; fields = null; } if ('function' == typeof options) { callback = options; options = null; } // make sure we don't send in the whole Document to merge() if (conditions instanceof Document) { conditions = conditions.toObject(); } if (options) { this.setOptions(options); } if (fields) { this.select(fields); } if (mquery.canMerge(conditions)) { this.merge(conditions); } prepareDiscriminatorCriteria(this); try { this.cast(this.model); this._castError = null; } catch (err) { this._castError = err; } if (!callback) { // already merged in the conditions, don't need to send them in. return Query.base.findOne.call(this); } var promise = new Promise(callback); if (this._castError) { promise.error(this._castError); return this; } this._applyPaths(); this._fields = this._castFields(this._fields); var options = this._mongooseOptions; var fields = this._fieldsForExec(); var self = this; // don't pass in the conditions because we already merged them in Query.base.findOne.call(this, {}, function cb (err, doc) { if (err) return promise.error(err); if (!doc) return promise.complete(null); if (!options.populate) { return true === options.lean ? promise.complete(doc) : completeOne(self.model, doc, fields, self, null, promise); } var pop = helpers.preparePopulationOptionsMQ(self, options); self.model.populate(doc, pop, function (err, doc) { if (err) return promise.error(err); return true === options.lean ? promise.complete(doc) : completeOne(self.model, doc, fields, self, pop, promise); }); }) return this; }
Query#findOneAndRemove(
[conditions]
,[options]
,[callback]
)Issues a mongodb findAndModify remove command.
Returns:
- <Query> this
See:
Finds a matching document, removes it, passing the found document (if any) to the callback. Executes immediately if
callback
is passed.Available options
sort
: if multiple docs are found by the conditions, sets the sort order to choose which doc to update
Examples
A.where().findOneAndRemove(conditions, options, callback) // executes A.where().findOneAndRemove(conditions, options) // return Query A.where().findOneAndRemove(conditions, callback) // executes A.where().findOneAndRemove(conditions) // returns Query A.where().findOneAndRemove(callback) // executes A.where().findOneAndRemove() // returns Query
Query#findOneAndUpdate(
[query]
,[doc]
,[options]
,[callback]
)Issues a mongodb findAndModify update command.
Returns:
- <Query> this
See:
Finds a matching document, updates it according to the
update
arg, passing anyoptions
, and returns the found document (if any) to the callback. The query executes immediately ifcallback
is passed.Available options
new
: bool - true to return the modified document rather than the original. defaults to trueupsert
: bool - creates the object if it doesn't exist. defaults to false.sort
: if multiple docs are found by the conditions, sets the sort order to choose which doc to update
Examples
query.findOneAndUpdate(conditions, update, options, callback) // executes query.findOneAndUpdate(conditions, update, options) // returns Query query.findOneAndUpdate(conditions, update, callback) // executes query.findOneAndUpdate(conditions, update) // returns Query query.findOneAndUpdate(update, callback) // returns Query query.findOneAndUpdate(update) // returns Query query.findOneAndUpdate(callback) // executes query.findOneAndUpdate() // returns Query
Query#geometry(
object
)Specifies a
$geometry
conditionParameters:
object
<Object> Must contain a `type` property which is a String and a `coordinates` property which is an Array. See the examples.
Returns:
- <Query> this
See:
Example
var polyA = [[[ 10, 20 ], [ 10, 40 ], [ 30, 40 ], [ 30, 20 ]]] query.where('loc').within().geometry({ type: 'Polygon', coordinates: polyA }) // or var polyB = [[ 0, 0 ], [ 1, 1 ]] query.where('loc').within().geometry({ type: 'LineString', coordinates: polyB }) // or var polyC = [ 0, 0 ] query.where('loc').within().geometry({ type: 'Point', coordinates: polyC }) // or 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 eitherintersects()
orwithin()
.The
object
argument must containtype
andcoordinates
properties.
- type {String}
- coordinates {Array}Query#gt(
[path]
,val
)Specifies a $gt query condition.
See:
When called with one argument, the most recent path passed to
where()
is used.Example
Thing.find().where('age').gt(21) // or Thing.find().gt('age', 21)
Query#gte(
[path]
,val
)Specifies a $gte query condition.
See:
When called with one argument, the most recent path passed to
where()
is used.Query#hint(
val
)Sets query hints.
Parameters:
val
<Object> a hint object
Returns:
- <Query> this
See:
Example
query.hint({ indexA: 1, indexB: -1})
Note
Cannot be used with
distinct()
Query#in(
[path]
,val
)Specifies an $in query condition.
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:
[arg]
<Object>
Returns:
- <Query> this
Example
query.where('path').intersects().geometry({ type: 'LineString' , coordinates: [[180.0, 11.0], [180, 9.0]] }) query.where('path').intersects({ type: 'LineString' , coordinates: [[180.0, 11.0], [180, 9.0]] })
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:
bool
<Boolean> defaults to true
Returns:
- <Query> this
show codeDocuments returned from queries with the
lean
option enabled are plain javascript objects, not MongooseDocuments. They have nosave
method, getters/setters or other Mongoose magic applied.Example:
new Query().lean() // true new Query().lean(true) new Query().lean(false) Model.find().lean().exec(function (err, docs) { docs[0] instanceof mongoose.Document // false });
This is a great option in high-performance read-only scenarios, especially when combined with stream.
Query.prototype.lean = function (v) { this._mongooseOptions.lean = arguments.length ? !!v : true; return this; }
Query#limit(
val
)Specifies the maximum number of documents the query will return.
Parameters:
val
<Number>
Example
query.limit(20)
Note
Cannot be used with
distinct()
Query#lt(
[path]
,val
)Specifies a $lt query condition.
See:
When called with one argument, the most recent path passed to
where()
is used.Query#lte(
[path]
,val
)Specifies a $lte query condition.
See:
When called with one argument, the most recent path passed to
where()
is used.Query#maxDistance(
[path]
,val
)Specifies a $maxDistance query condition.
See:
When called with one argument, the most recent path passed to
where()
is used.Query#maxScan(
val
)Specifies the maxScan option.
Parameters:
val
<Number>
See:
Example
query.maxScan(100)
Note
Cannot be used with
distinct()
Query#merge(
source
)Merges another Query or conditions object into this one.
Returns:
- <Query> this
When a Query is passed, conditions, field selection and options are merged.
New in 3.7.0
Query#ne(
[path]
,val
)Specifies a $ne query condition.
See:
When called with one argument, the most recent path passed to
where()
is used.Query#near(
[path]
,val
)Specifies a
$near
or$nearSphere
conditionReturns:
- <Query> this
These operators return documents sorted by distance.
Example
query.where('loc').near({ center: [10, 10] }); query.where('loc').near({ center: [10, 10], maxDistance: 5 }); query.where('loc').near({ center: [10, 10], maxDistance: 5, spherical: true }); query.near('loc', { center: [10, 10], maxDistance: 5 });
Query#nearSphere()
DEPRECATED Specifies a
$nearSphere
conditionshow codeExample
query.where('loc').nearSphere({ center: [10, 10], maxDistance: 5 });
Deprecated. Use
query.near()
instead with thespherical
option set totrue
.Example
query.where('loc').near({ center: [10, 10], spherical: true });
Query.prototype.nearSphere = function () { this._mongooseOptions.nearSphere = true; this.near.apply(this, arguments); return this; }
Query#nin(
[path]
,val
)Specifies an $nin query condition.
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:
- <Query> this
See:
Example
query.nor([{ color: 'green' }, { status: 'ok' }])
Query#or(
array
)Specifies arguments for an
$or
condition.Parameters:
array
<Array> array of conditions
Returns:
- <Query> this
See:
Example
query.or([{ color: 'red' }, { status: 'emergency' }])
Query#polygon(
[path]
,[coordinatePairs...]
)Specifies a $polygon condition
Returns:
- <Query> this
Example
query.where('loc').within().polygon([10,20], [13, 25], [7,15]) 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 name of the model you wish to use for population. If not specified, the name is looked up from the Schema ref.[match]
<Object> Conditions for the population query[options]
<Object> Options for the population query (sort, etc)
Returns:
- <Query> this
show codeExample:
Kitten.findOne().populate('owner').exec(function (err, kitten) { console.log(kitten.owner.name) // Max }) Kitten.find().populate({ path: 'owner' , select: 'name' , match: { color: 'black' } , options: { sort: { name: -1 }} }).exec(function (err, kittens) { console.log(kittens[0].owner.name) // Zoopa }) // alternatively Kitten.find().populate('owner', 'name', null, {sort: { name: -1 }}).exec(function (err, kittens) { console.log(kittens[0].owner.name) // Zoopa })
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.
Query.prototype.populate = function () { var res = utils.populate.apply(null, arguments); var opts = this._mongooseOptions; if (!utils.isObject(opts.populate)) { opts.populate = {}; } for (var i = 0; i < res.length; ++i) { opts.populate[res[i].path] = res[i]; } return this; }
prepareDiscriminatorCriteria()
If the model is a discriminator type and not root, then add the key & value to the criteria.
show codefunction prepareDiscriminatorCriteria(query) { if (!query || !query.model || !query.model.schema) { return; } var schema = query.model.schema; if (schema && schema.discriminatorMapping && !schema.discriminatorMapping.isRoot) { query._conditions[schema.discriminatorMapping.key] = schema.discriminatorMapping.value; } }
Query#read(
pref
,[tags]
)Determines the MongoDB nodes from which to read.
Parameters:
Returns:
- <Query> this
Preferences:
primary - (default) Read from primary only. Operations will produce an error if primary is unavailable. Cannot be combined with tags. secondary Read from secondary if available, otherwise error. primaryPreferred Read from primary if available, otherwise a secondary. secondaryPreferred Read from a secondary if available, otherwise read from the primary. 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
p primary pp primaryPreferred s secondary sp secondaryPreferred n nearest
Example:
new Query().read('primary') new Query().read('p') // same as primary new Query().read('primaryPreferred') new Query().read('pp') // same as primaryPreferred new Query().read('secondary') new Query().read('s') // same as secondary new Query().read('secondaryPreferred') new Query().read('sp') // same as secondaryPreferred new Query().read('nearest') new Query().read('n') // same as nearest // read from secondaries with matching tags new Query().read('s', [{ dc:'sf', s: 1 },{ dc:'ma', s: 2 }])
Query#regex(
[path]
,val
)Specifies a $regex query condition.
See:
When called with one argument, the most recent path passed to
where()
is used.Query#remove(
[criteria]
,[callback]
)Declare and/or execute this query as a remove() operation.
Returns:
- <Query> this
See:
show codeExample
Model.remove({ artist: 'Anne Murray' }, callback)
Note
The operation is only executed when a callback is passed. To force execution without a callback (which would be an unsafe write), we must first call remove() and then execute it by using the
exec()
method.// not executed var query = Model.find().remove({ name: 'Anne Murray' }) // executed query.remove({ name: 'Anne Murray' }, callback) query.remove({ name: 'Anne Murray' }).remove(callback) // executed without a callback (unsafe write) query.exec() // summary query.remove(conds, fn); // executes query.remove(conds) query.remove(fn) // executes query.remove()
Query.prototype.remove = function (cond, callback) { if ('function' == typeof cond) { callback = cond; cond = null; } var cb = 'function' == typeof callback; try { this.cast(this.model); } catch (err) { if (cb) return process.nextTick(callback.bind(null, err)); return this; } return Query.base.remove.call(this, cond, callback); }
Query#select(
arg
)Specifies which document fields to include or exclude
Returns:
- <Query> this
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.Example
// include a and b, exclude c query.select('a b -c'); // or you may use object notation, useful when // you have keys already prefixed with a "-" query.select({a: 1, b: 1, c: 0}); // force inclusion of field excluded at schema level query.select('+path')
NOTE:
Cannot be used with
distinct()
.v2 had slightly different syntax such as allowing arrays of field names. This support was removed in v3.
Query#setOptions(
options
)Sets query options.
Parameters:
options
<Object>
show codeOptions:
- tailable *
- sort *
- limit *
- skip *
- maxscan *
- batchSize *
- comment *
- snapshot *
- hint *
- slaveOk *
- lean *
- safe
* denotes a query helper method is also available
Query.prototype.setOptions = function (options, overwrite) { // overwrite is only for internal use if (overwrite) { // ensure that _mongooseOptions & options are two different objects this._mongooseOptions = (options && utils.clone(options)) || {}; this.options = options || {}; if('populate' in options) { this.populate(this._mongooseOptions); } return this; } if (!(options && 'Object' == options.constructor.name)) { return this; } return Query.base.setOptions.call(this, options); }
Query#size(
[path]
,val
)Specifies a $size query condition.
See:
When called with one argument, the most recent path passed to
where()
is used.Example
MyModel.where('tags').size(0).exec(function (err, docs) { if (err) return handleError(err); assert(Array.isArray(docs)); console.log('documents with 0 tags', docs); })
Query#skip(
val
)Specifies the number of documents to skip.
Parameters:
val
<Number>
See:
Example
query.skip(100).limit(20)
Note
Cannot be used with
distinct()
Query#slaveOk(
v
)DEPRECATED Sets the slaveOk option.
Parameters:
v
<Boolean> defaults to true
Returns:
- <Query> this
Deprecated in MongoDB 2.2 in favor of read preferences.
Example:
query.slaveOk() // true query.slaveOk(true) query.slaveOk(false)
Query#slice(
[path]
,val
)Specifies a $slice projection for an array.
Returns:
- <Query> this
Example
query.slice('comments', 5) query.slice('comments', -5) query.slice('comments', [10, 5]) query.where('comments').slice(5) query.where('comments').slice([-10, 5])
Query#snapshot()
Specifies this query as a
snapshot
query.Returns:
- <Query> this
See:
Example
query.snapshot() // true query.snapshot(true) query.snapshot(false)
Note
Cannot be used with
distinct()
Query#sort(
arg
)Sets the sort order
Returns:
- <Query> this
See:
show codeIf 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
// sort by "field" ascending and "test" descending query.sort({ field: 'asc', test: -1 }); // equivalent query.sort('field -test');
Note
Cannot be used with
distinct()
Query.prototype.sort = function (arg) { var nArg = {}; if (arguments.length > 1) { throw new Error("sort() only takes 1 Argument"); } if (Array.isArray(arg)) { // time to deal with the terrible syntax for (var i=0; i < arg.length; i++) { if (!Array.isArray(arg[i])) throw new Error("Invalid sort() argument."); nArg[arg[i][0]] = arg[i][1]; } } else { nArg = arg; } return Query.base.sort.call(this, nArg); }
Query#stream(
[options]
)Returns a Node.js 0.8 style read stream interface.
Parameters:
[options]
<Object>
Returns:
See:
show codeExample
// follows the nodejs 0.8 stream api Thing.find({ name: /^hello/ }).stream().pipe(res) // manual streaming var stream = Thing.find({ name: /^hello/ }).stream(); stream.on('data', function (doc) { // do something with the mongoose document }).on('error', function (err) { // handle the error }).on('close', function () { // the stream is closed });
Valid options
transform
: optional function which accepts a mongoose document. The return value of the function will be emitted ondata
.
Example
// JSON.stringify all documents before emitting var stream = Thing.find().stream({ transform: JSON.stringify }); stream.pipe(writeStream);
Query.prototype.stream = function stream (opts) { return new QueryStream(this, opts); } // the rest of these are basically to support older Mongoose syntax with mquery
Query#tailable(
bool
)Sets the tailable option (for use with capped collections).
Parameters:
bool
<Boolean> defaults to true
See:
show codeExample
query.tailable() // true query.tailable(true) query.tailable(false)
Note
Cannot be used with
distinct()
Query.prototype.tailable = function (val, opts) { // we need to support the tailable({ awaitdata : true }) as well as the // tailable(true, {awaitdata :true}) syntax that mquery does not support if (val && val.constructor.name == 'Object') { opts = val; val = true; } if (val === undefined) { val = true; } if (opts && opts.awaitdata) this.options.awaitdata = true; return Query.base.tailable.call(this, val); }
Query#toConstructor()
Converts this query to a customized, reusable query constructor with all arguments and options retained.
Returns:
- <Query> subclass-of-Query
show codeExample
// Create a query for adventure movies and read from the primary // node in the replica-set unless it is down, in which case we'll // read from a secondary node. var query = Movie.find({ tags: 'adventure' }).read('primaryPreferred'); // create a custom Query constructor based off these settings var Adventure = query.toConstructor(); // Adventure is now a subclass of mongoose.Query and works the same way but with the // default query parameters and options set. Adventure().exec(callback) // further narrow down our query results while still using the previous settings Adventure().where({ name: /^Life/ }).exec(callback); // since Adventure is a stand-alone constructor we can also add our own // helper methods and getters without impacting global queries Adventure.prototype.startsWith = function (prefix) { this.where({ name: new RegExp('^' + prefix) }) return this; } Object.defineProperty(Adventure.prototype, 'highlyRated', { get: function () { this.where({ rating: { $gt: 4.5 }}); return this; } }) Adventure().highlyRated.startsWith('Life').exec(callback)
New in 3.7.3
Query.prototype.toConstructor = function toConstructor () { function CustomQuery (criteria, options) { if (!(this instanceof CustomQuery)) return new CustomQuery(criteria, options); Query.call(this, criteria, options || null); } util.inherits(CustomQuery, Query); // set inherited defaults var p = CustomQuery.prototype; p.options = {}; p.setOptions(this.options); p.op = this.op; p._conditions = utils.clone(this._conditions); p._fields = utils.clone(this._fields); p._update = utils.clone(this._update); p._path = this._path; p._distict = this._distinct; p._collection = this._collection; p.model = this.model; p.mongooseCollection = this.mongooseCollection; p._mongooseOptions = this._mongooseOptions; return CustomQuery; }
Query#update(
[criteria]
,[doc]
,[options]
,[callback]
)Declare and/or execute this query as an update() operation.
Parameters:
Returns:
- <Query> this
show codeAll paths passed that are not $atomic operations will become $set ops.
Example
Model.where({ _id: id }).update({ title: 'words' }) // becomes Model.where({ _id: id }).update({ $set: { title: 'words' }})
Note
Passing an empty object
{}
as the doc will result in a no-op unless theoverwrite
option is passed. Without theoverwrite
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 (which would be an unsafe write), we must first call update() and then execute it by using the
exec()
method.var q = Model.where({ _id: id }); q.update({ $set: { name: 'bob' }}).update(); // not executed q.update({ $set: { name: 'bob' }}).exec(); // executed as unsafe // keys that are not $atomic ops become $set. // this executes the same command as the previous example. q.update({ name: 'bob' }).exec(); // overwriting with empty docs var q = Model.where({ _id: id }).setOptions({ overwrite: true }) q.update({ }, callback); // executes // multi update with overwrite to empty doc var q = Model.where({ _id: id }); q.setOptions({ multi: true, overwrite: true }) q.update({ }); q.update(callback); // executed // multi updates Model.where() .update({ name: /^match/ }, { $set: { arr: [] }}, { multi: true }, callback) // more multi updates Model.where() .setOptions({ multi: true }) .update({ $set: { arr: [] }}, callback) // single update by default Model.where({ email: 'address@example.com' }) .update({ $inc: { counter: 1 }}, callback)
API summary
update(criteria, doc, options, cb) // executes update(criteria, doc, options) update(criteria, doc, cb) // executes update(criteria, doc) update(doc, cb) // executes update(doc) update(cb) // executes update(true) // executes (unsafe write) update()
Query.prototype.update = function (conditions, doc, options, callback) { if ('function' === typeof options) { // Scenario: update(conditions, doc, callback) callback = options; options = null; } else if ('function' === typeof doc) { // Scenario: update(doc, callback); callback = doc; doc = conditions; conditions = {}; options = null; } else if ('function' === typeof conditions) { callback = conditions; conditions = undefined; doc = undefined; options = undefined; } // make sure we don't send in the whole Document to merge() if (conditions instanceof Document) { conditions = conditions.toObject(); } // strict is an option used in the update checking, make sure it gets set if (options) { if ('strict' in options) { this._mongooseOptions.strict = options.strict; } } // if doc is undefined at this point, this means this function is being // executed by exec(not always see below). Grab the update doc from here in // order to validate // This could also be somebody calling update() or update({}). Probably not a // common use case, check for _update to make sure we don't do anything bad if (!doc && this._update) { doc = this._updateForExec(); } if (conditions) { this._conditions = conditions; } // validate the selector part of the query var castedQuery = castQuery(this); if (castedQuery instanceof Error) { if(callback) { callback(castedQuery); return this; } else { throw castedQuery; } } // validate the update part of the query var castedDoc; try { castedDoc = this._castUpdate(doc, options && options.overwrite); } catch (err) { if (callback) { callback(err); return this; } else { throw err; } } if (!castedDoc) { callback && callback(null, 0); return this; } return Query.base.update.call(this, castedQuery, castedDoc, options, callback); }
Query#where(
[path]
,[val]
)Specifies a
path
for use with chaining.Returns:
- <Query> this
Example
// instead of writing: User.find({age: {$gte: 21, $lte: 65}}, callback); // we can instead write: User.where('age').gte(21).lte(65); // passing query conditions is permitted User.find().where({ name: 'vonderful' }) // chaining User .where('age').gte(21).lte(65) .where('name', /^vonderful/i) .where('friends').slice(10) .exec(callback)
Query#within()
Defines a
$within
or$geoWithin
argument for geo-spatial queries.Returns:
- <Query> this
Example
query.where(path).within().box() query.where(path).within().circle() query.where(path).within().geometry() query.where('loc').within({ center: [50,50], radius: 10, unique: true, spherical: true }); query.where('loc').within({ box: [[40.73, -73.9], [40.7, -73.988]] }); query.where('loc').within({ polygon: [[],[],[],[]] }); query.where('loc').within([], [], []) // polygon query.where('loc').within([], []) // box 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#use$geoWithin
Flag to opt out of using
$geoWithin
.mongoose.Query.use$geoWithin = false;
MongoDB 2.4 deprecated the use of
show code$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 tofalse
so yourwithin()
queries continue to work.Query.use$geoWithin = mquery.use$geoWithin;
- querystream.js
QueryStream(
query
,[options]
)Provides a Node.js 0.8 style ReadStream interface for Queries.
Inherits:
Events:
data
: emits a single Mongoose documenterror
: emits when an error occurs during streaming. This will emit before theclose
event.close
: emits when the stream reaches the end of the cursor or an error occurs, or the stream is manuallydestroy
ed. After this event, no more events are emitted.
show codevar stream = Model.find().stream(); stream.on('data', function (doc) { // do something with the mongoose document }).on('error', function (err) { // handle the error }).on('close', function () { // the stream is closed });
The stream interface allows us to simply "plug-in" to other Node.js 0.8 style write streams.
Model.where('created').gte(twoWeeksAgo).stream().pipe(writeStream);
Valid options
transform
: optional function which accepts a mongoose document. The return value of the function will be emitted ondata
.
Example
// JSON.stringify all documents before emitting var stream = Thing.find().stream({ transform: JSON.stringify }); stream.pipe(writeStream);
NOTE: plugging into an HTTP response will *not* work out of the box. Those streams expect only strings or buffers to be emitted, so first formatting our documents as strings/buffers is necessary.
NOTE: these streams are Node.js 0.8 style read streams which differ from Node.js 0.10 style. Node.js 0.10 streams are not well tested yet and are not guaranteed to work.
function QueryStream (query, options) { Stream.call(this); this.query = query; this.readable = true; this.paused = false; this._cursor = null; this._destroyed = null; this._fields = null; this._buffer = null; this._inline = T_INIT; this._running = false; this._transform = options && 'function' == typeof options.transform ? options.transform : K; // give time to hook up events var self = this; process.nextTick(function () { self._init(); }); }
QueryStream#__next()
Pulls the next doc from the cursor.
show codeQueryStream.prototype.__next = function () { if (this.paused || this._destroyed) return this._running = false; var self = this; self._inline = T_INIT; self._cursor.nextObject(function cursorcb (err, doc) { self._onNextObject(err, doc); }); // if onNextObject() was already called in this tick // return ourselves to the trampoline. if (T_CONT === this._inline) { return true; } else { // onNextObject() hasn't fired yet. tell onNextObject // that its ok to call _next b/c we are not within // the trampoline anymore. this._inline = T_IDLE; } }
QueryStream#_init()
Initializes the query.
show codeQueryStream.prototype._init = function () { if (this._destroyed) return; var query = this.query , model = query.model , options = query._optionsForExec(model) , self = this try { query.cast(model); } catch (err) { return self.destroy(err); } self._fields = utils.clone(query._fields); options.fields = query._castFields(self._fields); model.collection.find(query._conditions, options, function (err, cursor) { if (err) return self.destroy(err); self._cursor = cursor; self._next(); }); }
QueryStream#_next()
Trampoline for pulling the next doc from cursor.
show codeQueryStream.prototype._next = function _next () { if (this.paused || this._destroyed) { return this._running = false; } this._running = true; if (this._buffer && this._buffer.length) { var arg; while (!this.paused && !this._destroyed && (arg = this._buffer.shift())) { this._onNextObject.apply(this, arg); } } // avoid stack overflows with large result sets. // trampoline instead of recursion. while (this.__next()) {} }
QueryStream#_onNextObject(
err
,doc
)Transforms raw
show codedoc
s returned from the cursor into a model instance.QueryStream.prototype._onNextObject = function _onNextObject (err, doc) { if (this._destroyed) return; if (this.paused) { this._buffer || (this._buffer = []); this._buffer.push([err, doc]); return this._running = false; } if (err) return this.destroy(err); // when doc is null we hit the end of the cursor if (!doc) { this.emit('end'); return this.destroy(); } var opts = this.query._mongooseOptions; if (!opts.populate) { return true === opts.lean ? emit(this, doc) : createAndEmit(this, doc); } var self = this; var pop = helpers.preparePopulationOptionsMQ(self.query, self.query._mongooseOptions); self.query.model.populate(doc, pop, function (err, doc) { if (err) return self.destroy(err); return true === opts.lean ? emit(self, doc) : createAndEmit(self, doc); }) } function createAndEmit (self, doc) { var instance = new self.query.model(undefined, self._fields, true); instance.init(doc, function (err) { if (err) return self.destroy(err); emit(self, instance); }); }
QueryStream#destroy(
[err]
)Destroys the stream, closing the underlying cursor. No more events will be emitted.
show codeParameters:
[err]
<Error>
QueryStream.prototype.destroy = function (err) { if (this._destroyed) return; this._destroyed = true; this._running = false; this.readable = false; if (this._cursor) { this._cursor.close(); } if (err) { this.emit('error', err); } this.emit('close'); }
QueryStream#pause()
Pauses this stream.
show codeQueryStream.prototype.pause = function () { this.paused = true; }
QueryStream#pipe()
Pipes this query stream into another stream. This method is inherited from NodeJS Streams.
See:
Example:
query.stream().pipe(writeStream [, options])
QueryStream#resume()
Resumes this stream.
show codeQueryStream.prototype.resume = function () { this.paused = false; if (!this._cursor) { // cannot start if not initialized return; } // are we within the trampoline? if (T_INIT === this._inline) { return; } if (!this._running) { // outside QueryStream control, need manual restart return this._next(); } }
QueryStream#paused
Flag stating whether or not this stream is paused.
show codeQueryStream.prototype.paused; // trampoline flags var T_INIT = 0; var T_IDLE = 1; var T_CONT = 2;
QueryStream#readable
Flag stating whether or not this stream is readable.
show codeQueryStream.prototype.readable;
- schema/array.js
SchemaArray(
key
,cast
,options
)Array SchemaType constructor
Parameters:
key
<String>cast
<SchemaType>options
<Object>
show codeInherits:
function SchemaArray (key, cast, options) { if (cast) { var castOptions = {}; if ('Object' === cast.constructor.name) { if (cast.type) { // support { type: Woot } castOptions = utils.clone(cast); // do not alter user arguments delete castOptions.type; cast = cast.type; } else { cast = Mixed; } } // support { type: 'String' } var name = 'string' == typeof cast ? cast : cast.name; var caster = name in Types ? Types[name] : cast; this.casterConstructor = caster; this.caster = new caster(null, castOptions); if (!(this.caster instanceof EmbeddedDoc)) { this.caster.path = key; } } SchemaType.call(this, key, options); var self = this , defaultArr , fn; if (this.defaultValue) { defaultArr = this.defaultValue; fn = 'function' == typeof defaultArr; } this.default(function(){ var arr = fn ? defaultArr() : defaultArr || []; return new MongooseArray(arr, self.path, this); }); };
SchemaArray#applyGetters(
value
,scope
)Overrides the getters application for the population special-case
show codeSchemaArray.prototype.applyGetters = function (value, scope) { if (this.caster.options && this.caster.options.ref) { // means the object id was populated return value; } return SchemaType.prototype.applyGetters.call(this, value, scope); };
SchemaArray#cast(
value
,doc
,init
)Casts values for set().
show codeParameters:
SchemaArray.prototype.cast = function (value, doc, init) { if (Array.isArray(value)) { if (!(value instanceof MongooseArray)) { value = new MongooseArray(value, this.path, doc); } if (this.caster) { try { for (var i = 0, l = value.length; i < l; i++) { value[i] = this.caster.cast(value[i], doc, init); } } catch (e) { // rethrow throw new CastError(e.type, value, this.path); } } return value; } else { return this.cast([value], doc, init); } };
SchemaArray#castForQuery(
$conditional
,[value]
)Casts values for queries.
show codeParameters:
$conditional
<String>[value]
<T>
SchemaArray.prototype.castForQuery = function ($conditional, value) { var handler , val; if (arguments.length === 2) { handler = this.$conditionalHandlers[$conditional]; if (!handler) { throw new Error("Can't use " + $conditional + " with Array."); } val = handler.call(this, value); } else { val = $conditional; var proto = this.casterConstructor.prototype; var method = proto.castForQuery || proto.cast; var caster = this.caster; if (Array.isArray(val)) { val = val.map(function (v) { if (method) v = method.call(caster, v); return isMongooseObject(v) ? v.toObject() : v; }); } else if (method) { val = method.call(caster, val); } } return val && isMongooseObject(val) ? val.toObject() : val; };
SchemaArray#checkRequired(
value
)Check required
show codeParameters:
value
<Array>
SchemaArray.prototype.checkRequired = function (value) { return !!(value && value.length); };
- schema/boolean.js
SchemaBoolean(
path
,options
)Boolean SchemaType constructor.
show codeInherits:
function SchemaBoolean (path, options) { SchemaType.call(this, path, options); };
SchemaBoolean#cast(
value
)Casts to boolean
show codeParameters:
value
<Object>
SchemaBoolean.prototype.cast = function (value) { if (null === value) return value; if ('0' === value) return false; if ('true' === value) return true; if ('false' === value) return false; return !! value; }
SchemaBoolean#castForQuery(
$conditional
,val
)Casts contents for queries.
show codeParameters:
$conditional
<String>val
<T>
SchemaBoolean.prototype.castForQuery = function ($conditional, val) { var handler; if (2 === arguments.length) { handler = SchemaBoolean.$conditionalHandlers[$conditional]; if (handler) { return handler.call(this, val); } return this.cast(val); } return this.cast($conditional); };
SchemaBoolean#checkRequired()
Required validator
show codeSchemaBoolean.prototype.checkRequired = function (value) { return value === true || value === false; };
- schema/buffer.js
SchemaBuffer(
key
,cast
)Buffer SchemaType constructor
Parameters:
key
<String>cast
<SchemaType>
show codeInherits:
function SchemaBuffer (key, options) { SchemaType.call(this, key, options, 'Buffer'); };
SchemaBuffer#cast(
value
,doc
,init
)Casts contents
show codeSchemaBuffer.prototype.cast = function (value, doc, init) { if (SchemaType._isRef(this, value, doc, init)) { // wait! we may need to cast this to a document if (null == value) { return value; } // lazy load Document || (Document = require('./../document')); if (value instanceof Document) { value.$__.wasPopulated = true; return value; } // setting a populated path if (Buffer.isBuffer(value)) { return value; } else if (!utils.isObject(value)) { throw new CastError('buffer', value, this.path); } // Handle the case where user directly sets a populated // path to a plain object; cast to the Model used in // the population query. var path = doc.$__fullPath(this.path); var owner = doc.ownerDocument ? doc.ownerDocument() : doc; var pop = owner.populated(path, true); var ret = new pop.options.model(value); ret.$__.wasPopulated = true; return ret; } // documents if (value && value._id) { value = value._id; } if (Buffer.isBuffer(value)) { if (!(value instanceof MongooseBuffer)) { value = new MongooseBuffer(value, [this.path, doc]); } return value; } else if (value instanceof Binary) { var ret = new MongooseBuffer(value.value(true), [this.path, doc]); ret.subtype(value.sub_type); // do not override Binary subtypes. users set this // to whatever they want. return ret; } if (null === value) return value; var type = typeof value; if ('string' == type || 'number' == type || Array.isArray(value)) { var ret = new MongooseBuffer(value, [this.path, doc]); return ret; } throw new CastError('buffer', value, this.path); };
SchemaBuffer#castForQuery(
$conditional
,[value]
)Casts contents for queries.
show codeParameters:
$conditional
<String>[value]
<T>
SchemaBuffer.prototype.castForQuery = function ($conditional, val) { var handler; if (arguments.length === 2) { handler = this.$conditionalHandlers[$conditional]; if (!handler) throw new Error("Can't use " + $conditional + " with Buffer."); return handler.call(this, val); } else { val = $conditional; return this.cast(val).toObject(); } };
SchemaBuffer#checkRequired()
Check required
show codeSchemaBuffer.prototype.checkRequired = function (value, doc) { if (SchemaType._isRef(this, value, doc, true)) { return null != value; } else { return !!(value && value.length); } };
- schema/date.js
SchemaDate(
key
,options
)Date SchemaType constructor.
show codeInherits:
function SchemaDate (key, options) { SchemaType.call(this, key, options); };
SchemaDate#cast(
value
)Casts to date
show codeParameters:
value
<Object> to cast
SchemaDate.prototype.cast = function (value) { if (value === null || value === '') return null; if (value instanceof Date) return value; var date; // support for timestamps if (value instanceof Number || 'number' == typeof value || String(value) == Number(value)) date = new Date(Number(value)); // support for date strings else if (value.toString) date = new Date(value.toString()); if (date.toString() != 'Invalid Date') return date; throw new CastError('date', value, this.path); };
SchemaDate#castForQuery(
$conditional
,[value]
)Casts contents for queries.
show codeParameters:
$conditional
<String>[value]
<T>
SchemaDate.prototype.castForQuery = function ($conditional, val) { var handler; if (2 !== arguments.length) { return this.cast($conditional); } handler = this.$conditionalHandlers[$conditional]; if (!handler) { throw new Error("Can't use " + $conditional + " with Date."); } return handler.call(this, val); };
SchemaDate#checkRequired()
Required validator for date
show codeSchemaDate.prototype.checkRequired = function (value) { return value instanceof Date; };
SchemaDate#expires(
when
)Declares a TTL index (rounded to the nearest second) for Date types only.
Returns:
- <SchemaType> this
show codeThis sets the
expiresAfterSeconds
index option available in MongoDB >= 2.1.2.
This index type is only compatible with Date types.Example:
// expire in 24 hours new Schema({ createdAt: { type: Date, expires: 60*60*24 }});
expires
utilizes thems
module from guille allowing us to use a friendlier syntax:Example:
// expire in 24 hours new Schema({ createdAt: { type: Date, expires: '24h' }}); // expire in 1.5 hours new Schema({ createdAt: { type: Date, expires: '1.5h' }}); // expire in 7 days var schema = new Schema({ createdAt: Date }); schema.path('createdAt').expires('7d');
SchemaDate.prototype.expires = function (when) { if (!this._index || 'Object' !== this._index.constructor.name) { this._index = {}; } this._index.expires = when; utils.expires(this._index); return this; };
- schema/documentarray.js
DocumentArray(
key
,schema
,options
)SubdocsArray SchemaType constructor
show codeInherits:
function DocumentArray (key, schema, options) { // compile an embedded document for this schema function EmbeddedDocument () { Subdocument.apply(this, arguments); } EmbeddedDocument.prototype.__proto__ = Subdocument.prototype; EmbeddedDocument.prototype.$__setSchema(schema); EmbeddedDocument.schema = schema; // apply methods for (var i in schema.methods) { EmbeddedDocument.prototype[i] = schema.methods[i]; } // apply statics for (var i in schema.statics) EmbeddedDocument[i] = schema.statics[i]; EmbeddedDocument.options = options; this.schema = schema; ArrayType.call(this, key, EmbeddedDocument, options); this.schema = schema; var path = this.path; var fn = this.defaultValue; this.default(function(){ var arr = fn.call(this); if (!Array.isArray(arr)) arr = [arr]; return new MongooseDocumentArray(arr, path, this); }); };
DocumentArray#cast(
value
,document
)Casts contents
show codeDocumentArray.prototype.cast = function (value, doc, init, prev) { var selected , subdoc , i if (!Array.isArray(value)) { return this.cast([value], doc, init, prev); } if (!(value instanceof MongooseDocumentArray)) { value = new MongooseDocumentArray(value, this.path, doc); } i = value.length; while (i--) { if (!(value[i] instanceof Subdocument) && value[i]) { if (init) { selected || (selected = scopePaths(this, doc.$__.selected, init)); subdoc = new this.casterConstructor(null, value, true, selected); value[i] = subdoc.init(value[i]); } else { if (prev && (subdoc = prev.id(value[i]._id))) { // handle resetting doc with existing id but differing data // doc.array = [{ doc: 'val' }] subdoc.set(value[i]); } else { subdoc = new this.casterConstructor(value[i], value); } // if set() is hooked it will have no return value // see gh-746 value[i] = subdoc; } } } return value; }
DocumentArray#doValidate()
Performs local validations first, then validations on each embedded doc
show codeDocumentArray.prototype.doValidate = function (array, fn, scope) { var self = this; SchemaType.prototype.doValidate.call(this, array, function (err) { if (err) return fn(err); var count = array && array.length , error; if (!count) return fn(); // handle sparse arrays, do not use array.forEach which does not // iterate over sparse elements yet reports array.length including // them :( for (var i = 0, len = count; i < len; ++i) { // sidestep sparse entries var doc = array[i]; if (!doc) { --count || fn(); continue; } ;(function (i) { doc.validate(function (err) { if (err && !error) { // rewrite the key err.key = self.key + '.' + i + '.' + err.key; return fn(error = err); } --count || fn(); }); })(i); } }, scope); };
- schema/mixed.js
Mixed(
path
,options
)Mixed SchemaType constructor.
show codeInherits:
function Mixed (path, options) { if (options && options.default) { var def = options.default; if (Array.isArray(def) && 0 === def.length) { // make sure empty array defaults are handled options.default = Array; } else if (!options.shared && utils.isObject(def) && 0 === Object.keys(def).length) { // prevent odd "shared" objects between documents options.default = function () { return {} } } } SchemaType.call(this, path, options); };
Mixed#cast(
value
)Casts
val
for Mixed.Parameters:
value
<Object> to cast
show codethis is a no-op
Mixed.prototype.cast = function (val) { return val; };
Mixed#castForQuery(
$cond
,[val]
)Casts contents for queries.
show codeParameters:
$cond
<String>[val]
<T>
Mixed.prototype.castForQuery = function ($cond, val) { if (arguments.length === 2) return val; return $cond; };
Mixed#checkRequired()
Required validator
show codeMixed.prototype.checkRequired = function (val) { return true; };
- schema/number.js
SchemaNumber(
key
,options
)Number SchemaType constructor.
show codeInherits:
function SchemaNumber (key, options) { SchemaType.call(this, key, options, 'Number'); };
SchemaNumber#cast(
value
,doc
,init
)Casts to number
show codeParameters:
SchemaNumber.prototype.cast = function (value, doc, init) { if (SchemaType._isRef(this, value, doc, init)) { // wait! we may need to cast this to a document if (null == value) { return value; } // lazy load Document || (Document = require('./../document')); if (value instanceof Document) { value.$__.wasPopulated = true; return value; } // setting a populated path if ('number' == typeof value) { return value; } else if (Buffer.isBuffer(value) || !utils.isObject(value)) { throw new CastError('number', value, this.path); } // Handle the case where user directly sets a populated // path to a plain object; cast to the Model used in // the population query. var path = doc.$__fullPath(this.path); var owner = doc.ownerDocument ? doc.ownerDocument() : doc; var pop = owner.populated(path, true); var ret = new pop.options.model(value); ret.$__.wasPopulated = true; return ret; } var val = value && value._id ? value._id // documents : value; if (!isNaN(val)){ if (null === val) return val; if ('' === val) return null; if ('string' == typeof val) val = Number(val); if (val instanceof Number) return val if ('number' == typeof val) return val; if (val.toString && !Array.isArray(val) && val.toString() == Number(val)) { return new Number(val) } } throw new CastError('number', value, this.path); };
SchemaNumber#castForQuery(
$conditional
,[value]
)Casts contents for queries.
show codeParameters:
$conditional
<String>[value]
<T>
SchemaNumber.prototype.castForQuery = function ($conditional, val) { var handler; if (arguments.length === 2) { handler = this.$conditionalHandlers[$conditional]; if (!handler) throw new Error("Can't use " + $conditional + " with Number."); return handler.call(this, val); } else { val = this.cast($conditional); return val == null ? val : val } };
SchemaNumber#checkRequired()
Required validator for number
show codeSchemaNumber.prototype.checkRequired = function checkRequired (value, doc) { if (SchemaType._isRef(this, value, doc, true)) { return null != value; } else { return typeof value == 'number' || value instanceof Number; } };
SchemaNumber#max(
maximum
,[message]
)Sets a maximum number validator.
Returns:
- <SchemaType> this
show codeExample:
var s = new Schema({ n: { type: Number, max: 10 }) var M = db.model('M', s) var m = new M({ n: 11 }) m.save(function (err) { console.error(err) // validator error m.n = 10; m.save() // success }) // custom error messages // We can also use the special {MAX} token which will be replaced with the invalid value var max = [10, 'The value of path `{PATH}` ({VALUE}) exceeds the limit ({MAX}).']; var schema = new Schema({ n: { type: Number, max: max }) var M = mongoose.model('Measurement', schema); var s= new M({ n: 4 }); s.validate(function (err) { console.log(String(err)) // ValidationError: The value of path `n` (4) exceeds the limit (10). })
SchemaNumber.prototype.max = function (value, message) { if (this.maxValidator) { this.validators = this.validators.filter(function(v){ return v[0] != this.maxValidator; }, this); } if (null != value) { var msg = message || errorMessages.Number.max; msg = msg.replace(/{MAX}/, value); this.validators.push([this.maxValidator = function(v){ return v === null || v <= value; }, msg, 'max']); } return this; };
SchemaNumber#min(
value
,[message]
)Sets a minimum number validator.
Returns:
- <SchemaType> this
show codeExample:
var s = new Schema({ n: { type: Number, min: 10 }) var M = db.model('M', s) var m = new M({ n: 9 }) m.save(function (err) { console.error(err) // validator error m.n = 10; m.save() // success }) // custom error messages // We can also use the special {MIN} token which will be replaced with the invalid value var min = [10, 'The value of path `{PATH}` ({VALUE}) is beneath the limit ({MIN}).']; var schema = new Schema({ n: { type: Number, min: min }) var M = mongoose.model('Measurement', schema); var s= new M({ n: 4 }); s.validate(function (err) { console.log(String(err)) // ValidationError: The value of path `n` (4) is beneath the limit (10). })
SchemaNumber.prototype.min = function (value, message) { if (this.minValidator) { this.validators = this.validators.filter(function (v) { return v[0] != this.minValidator; }, this); } if (null != value) { var msg = message || errorMessages.Number.min; msg = msg.replace(/{MIN}/, value); this.validators.push([this.minValidator = function (v) { return v === null || v >= value; }, msg, 'min']); } return this; };
- schema/objectid.js
ObjectId(
key
,options
)ObjectId SchemaType constructor.
show codeInherits:
function ObjectId (key, options) { SchemaType.call(this, key, options, 'ObjectID'); };
ObjectId#auto(
turnOn
)Adds an auto-generated ObjectId default if turnOn is true.
Parameters:
turnOn
<Boolean> auto generated ObjectId defaults
show codeReturns:
- <SchemaType> this
ObjectId.prototype.auto = function (turnOn) { if (turnOn) { this.default(defaultId); this.set(resetId) } return this; };
ObjectId#cast(
value
,doc
,init
)Casts to ObjectId
show codeObjectId.prototype.cast = function (value, doc, init) { if (SchemaType._isRef(this, value, doc, init)) { // wait! we may need to cast this to a document if (null == value) { return value; } // lazy load Document || (Document = require('./../document')); if (value instanceof Document) { value.$__.wasPopulated = true; return value; } // setting a populated path if (value instanceof oid) { return value; } else if (Buffer.isBuffer(value) || !utils.isObject(value)) { throw new CastError('ObjectId', value, this.path); } // Handle the case where user directly sets a populated // path to a plain object; cast to the Model used in // the population query. var path = doc.$__fullPath(this.path); var owner = doc.ownerDocument ? doc.ownerDocument() : doc; var pop = owner.populated(path, true); var ret = new pop.options.model(value); ret.$__.wasPopulated = true; return ret; } if (value === null) return value; if (value instanceof oid) return value; if (value._id && value._id instanceof oid) return value._id; if (value.toString) { try { return oid.createFromHexString(value.toString()); } catch (err) { throw new CastError('ObjectId', value, this.path); } } throw new CastError('ObjectId', value, this.path); };
ObjectId#castForQuery(
$conditional
,[val]
)Casts contents for queries.
show codeParameters:
$conditional
<String>[val]
<T>
ObjectId.prototype.castForQuery = function ($conditional, val) { var handler; if (arguments.length === 2) { handler = this.$conditionalHandlers[$conditional]; if (!handler) throw new Error("Can't use " + $conditional + " with ObjectId."); return handler.call(this, val); } else { return this.cast($conditional); } };
ObjectId#checkRequired()
Check required
show codeObjectId.prototype.checkRequired = function checkRequired (value, doc) { if (SchemaType._isRef(this, value, doc, true)) { return null != value; } else { return value instanceof oid; } };
- schema/string.js
SchemaString(
key
,options
)String SchemaType constructor.
show codeInherits:
function SchemaString (key, options) { this.enumValues = []; this.regExp = null; SchemaType.call(this, key, options, 'String'); };
SchemaString#cast()
Casts to String
show codeSchemaString.prototype.cast = function (value, doc, init) { if (SchemaType._isRef(this, value, doc, init)) { // wait! we may need to cast this to a document if (null == value) { return value; } // lazy load Document || (Document = require('./../document')); if (value instanceof Document) { value.$__.wasPopulated = true; return value; } // setting a populated path if ('string' == typeof value) { return value; } else if (Buffer.isBuffer(value) || !utils.isObject(value)) { throw new CastError('string', value, this.path); } // Handle the case where user directly sets a populated // path to a plain object; cast to the Model used in // the population query. var path = doc.$__fullPath(this.path); var owner = doc.ownerDocument ? doc.ownerDocument() : doc; var pop = owner.populated(path, true); var ret = new pop.options.model(value); ret.$__.wasPopulated = true; return ret; } if (value === null) { return value; } if ('undefined' !== typeof value) { // handle documents being passed if (value._id && 'string' == typeof value._id) { return value._id; } if (value.toString) { return value.toString(); } } throw new CastError('string', value, this.path); };
SchemaString#castForQuery(
$conditional
,[val]
)Casts contents for queries.
show codeParameters:
$conditional
<String>[val]
<T>
SchemaString.prototype.castForQuery = function ($conditional, val) { var handler; if (arguments.length === 2) { handler = this.$conditionalHandlers[$conditional]; if (!handler) throw new Error("Can't use " + $conditional + " with String."); return handler.call(this, val); } else { val = $conditional; if (val instanceof RegExp) return val; return this.cast(val); } };
SchemaString#checkRequired(
value
)Check required
show codeSchemaString.prototype.checkRequired = function checkRequired (value, doc) { if (SchemaType._isRef(this, value, doc, true)) { return null != value; } else { return (value instanceof String || typeof value == 'string') && value.length; } };
SchemaString#enum(
[args...]
)Adds an enum validator
Returns:
- <SchemaType> this
show codeExample:
var states = 'opening open closing closed'.split(' ') var s = new Schema({ state: { type: String, enum: states }}) var M = db.model('M', s) var m = new M({ state: 'invalid' }) m.save(function (err) { console.error(String(err)) // ValidationError: `invalid` is not a valid enum value for path `state`. m.state = 'open' m.save(callback) // success }) // or with custom error messages var enu = { values: 'opening open closing closed'.split(' '), message: 'enum validator failed for path `{PATH}` with value `{VALUE}`' } var s = new Schema({ state: { type: String, enum: enu }) var M = db.model('M', s) var m = new M({ state: 'invalid' }) m.save(function (err) { console.error(String(err)) // ValidationError: enum validator failed for path `state` with value `invalid` m.state = 'open' m.save(callback) // success })
SchemaString.prototype.enum = function () { var len = arguments.length; if (this.enumValidator) { this.validators = this.validators.filter(function(v){ return v[0] != this.enumValidator; }, this); this.enumValidator = false; } if (undefined === arguments[0] || false === arguments[0]) { return this; } var values; if (utils.isObject(arguments[0])) { values = arguments[0].values; errorMessage = arguments[0].message; } else { values = arguments; errorMessage = errorMessages.String.enum; } for (var i = 0; i < len; i++) { if (undefined !== values[i]) { this.enumValues.push(this.cast(values[i])); } } var vals = this.enumValues; this.enumValidator = function (v) { return undefined === v || ~vals.indexOf(v); }; this.validators.push([this.enumValidator, errorMessage, 'enum']); return this; };
SchemaString#lowercase()
Adds a lowercase setter.
Returns:
- <SchemaType> this
show codeExample:
var s = new Schema({ email: { type: String, lowercase: true }}) var M = db.model('M', s); var m = new M({ email: 'SomeEmail@example.COM' }); console.log(m.email) // someemail@example.com
SchemaString.prototype.lowercase = function () { return this.set(function (v, self) { if ('string' != typeof v) v = self.cast(v) if (v) return v.toLowerCase(); return v; }); };
SchemaString#match(
regExp
,[message]
)Sets a regexp validator.
Parameters:
Returns:
- <SchemaType> this
show codeAny value that does not pass
regExp
.test(val) will fail validation.Example:
var s = new Schema({ name: { type: String, match: /^a/ }}) var M = db.model('M', s) var m = new M({ name: 'I am invalid' }) m.validate(function (err) { console.error(String(err)) // "ValidationError: Path `name` is invalid (I am invalid)." m.name = 'apples' m.validate(function (err) { assert.ok(err) // success }) }) // using a custom error message var match = [ /\.html$/, "That file doesn't end in .html ({VALUE})" ]; var s = new Schema({ file: { type: String, match: match }}) var M = db.model('M', s); var m = new M({ file: 'invalid' }); m.validate(function (err) { console.log(String(err)) // "ValidationError: That file doesn't end in .html (invalid)" })
Empty strings,
undefined
, andnull
values always pass the match validator. If you require these values, enable therequired
validator also.var s = new Schema({ name: { type: String, match: /^a/, required: true }})
SchemaString.prototype.match = function match (regExp, message) { // yes, we allow multiple match validators var msg = message || errorMessages.String.match; function matchValidator (v){ return null != v && '' !== v ? regExp.test(v) : true } this.validators.push([matchValidator, msg, 'regexp']); return this; };
SchemaString#trim()
Adds a trim setter.
Returns:
- <SchemaType> this
show codeThe string value will be trimmed when set.
Example:
var s = new Schema({ name: { type: String, trim: true }}) var M = db.model('M', s) var string = ' some name ' console.log(string.length) // 11 var m = new M({ name: string }) console.log(m.name.length) // 9
SchemaString.prototype.trim = function () { return this.set(function (v, self) { if ('string' != typeof v) v = self.cast(v) if (v) return v.trim(); return v; }); };
SchemaString#uppercase()
Adds an uppercase setter.
Returns:
- <SchemaType> this
show codeExample:
var s = new Schema({ caps: { type: String, uppercase: true }}) var M = db.model('M', s); var m = new M({ caps: 'an example' }); console.log(m.caps) // AN EXAMPLE
SchemaString.prototype.uppercase = function () { return this.set(function (v, self) { if ('string' != typeof v) v = self.cast(v) if (v) return v.toUpperCase(); return v; }); };
- schema.js
Schema(
definition
)Schema constructor.
Parameters:
definition
<Object>
Inherits:
Events:
init
: Emitted after the schema is compiled into aModel
.
show codeExample:
var child = new Schema({ name: String }); var schema = new Schema({ name: String, age: Number, children: [child] }); var Tree = mongoose.model('Tree', schema); // setting schema options new Schema({ name: String }, { _id: false, autoIndex: false })
Options:
- autoIndex: bool - defaults to true
- bufferCommands: bool - defaults to true
- capped: bool - defaults to false
- collection: string - no default
- id: bool - defaults to true
- _id: bool - defaults to true
minimize
: bool - controls document#toObject behavior when called manually - defaults to true- read: string
- safe: bool - defaults to true.
- shardKey: bool - defaults to
null
- strict: bool - defaults to true
- toJSON - object - no default
- toObject - object - no default
- versionKey: bool - defaults to "__v"
Note:
When nesting schemas, (
children
in the example above), always declare the child schema first before passing it into is parent.function Schema (obj, options) { if (!(this instanceof Schema)) return new Schema(obj, options); this.paths = {}; this.subpaths = {}; this.virtuals = {}; this.nested = {}; this.inherits = {}; this.callQueue = []; this._indexes = []; this.methods = {}; this.statics = {}; this.tree = {}; this._requiredpaths = undefined; this.discriminatorMapping = undefined; this.options = this.defaultOptions(options); // build paths if (obj) { this.add(obj); } // ensure the documents get an auto _id unless disabled var auto_id = !this.paths['_id'] && (!this.options.noId && this.options._id); if (auto_id) { this.add({ _id: {type: Schema.ObjectId, auto: true} }); } // ensure the documents receive an id getter unless disabled var autoid = !this.paths['id'] && (!this.options.noVirtualId && this.options.id); if (autoid) { this.virtual('id').get(idGetter); } }
Schema#add(
obj
,prefix
)Adds key path / schema type pairs to this schema.
show codeExample:
var ToySchema = new Schema; ToySchema.add({ name: 'string', color: 'string', price: 'number' });
Schema.prototype.add = function add (obj, prefix) { prefix = prefix || ''; var keys = Object.keys(obj); for (var i = 0; i < keys.length; ++i) { var key = keys[i]; if (null == obj[key]) { throw new TypeError('Invalid value for schema path `'+ prefix + key +'`'); } if (utils.isObject(obj[key]) && (!obj[key].constructor || 'Object' == obj[key].constructor.name) && (!obj[key].type || obj[key].type.type)) { if (Object.keys(obj[key]).length) { // nested object { last: { name: String }} this.nested[prefix + key] = true; this.add(obj[key], prefix + key + '.'); } else { this.path(prefix + key, obj[key]); // mixed type } } else { this.path(prefix + key, obj[key]); } } };
Schema#defaultOptions(
options
)Returns default options for this schema, merged with
options
.Parameters:
options
<Object>
show codeReturns:
- <Object>
Schema.prototype.defaultOptions = function (options) { if (options && false === options.safe) { options.safe = { w: 0 }; } if (options && options.safe && 0 === options.safe.w) { // if you turn off safe writes, then versioning goes off as well options.versionKey = false; } options = utils.options({ strict: true , bufferCommands: true , capped: false // { size, max, autoIndexId } , versionKey: '__v' , discriminatorKey: '__t' , minimize: true , autoIndex: true , shardKey: null , read: null // the following are only applied at construction time , noId: false // deprecated, use { _id: false } , _id: true , noVirtualId: false // deprecated, use { id: false } , id: true // , pluralization: true // only set this to override the global option }, options); if (options.read) { options.read = mquery.utils.readPref(options.read); } return options; }
Schema#eachPath(
fn
)Iterates the schemas paths similar to Array#forEach.
Parameters:
fn
<Function> callback function
Returns:
- <Schema> this
show codeThe callback is passed the pathname and schemaType as arguments on each iteration.
Schema.prototype.eachPath = function (fn) { var keys = Object.keys(this.paths) , len = keys.length; for (var i = 0; i < len; ++i) { fn(keys[i], this.paths[keys[i]]); } return this; };
Schema#get(
key
)Gets a schema option.
show codeParameters:
key
<String> option name
Schema.prototype.get = function (key) { return this.options[key]; }
Schema#index(
fields
,[options]
)Defines an index (most likely compound) for this schema.
show codeExample
schema.index({ first: 1, last: -1 })
Schema.prototype.index = function (fields, options) { options || (options = {}); if (options.expires) utils.expires(options); this._indexes.push([fields, options]); return this; };
Schema#indexes()
Compiles indexes from fields and schema-level indexes
show codeSchema.prototype.indexes = function () { 'use strict'; var indexes = [] , seenSchemas = [] collectIndexes(this); return indexes; function collectIndexes (schema, prefix) { if (~seenSchemas.indexOf(schema)) return; seenSchemas.push(schema); prefix = prefix || ''; var key, path, index, field, isObject, options, type; var keys = Object.keys(schema.paths); for (var i = 0; i < keys.length; ++i) { key = keys[i]; path = schema.paths[key]; if (path instanceof Types.DocumentArray) { collectIndexes(path.schema, key + '.'); } else { index = path._index; if (false !== index && null != index) { field = {}; isObject = utils.isObject(index); options = isObject ? index : {}; type = 'string' == typeof index ? index : isObject ? index.type : false; if (type && ~Schema.indexTypes.indexOf(type)) { field[prefix + key] = type; } else { field[prefix + key] = 1; } delete options.type; if (!('background' in options)) { options.background = true; } indexes.push([field, options]); } } } if (prefix) { fixSubIndexPaths(schema, prefix); } else { schema._indexes.forEach(function (index) { if (!('background' in index[1])) index[1].background = true; }); indexes = indexes.concat(schema._indexes); } }
Schema#method(
method
,[fn]
)Adds an instance method to documents constructed from Models compiled from this schema.
show codeExample
var schema = kittySchema = new Schema(..); schema.method('meow', function () { console.log('meeeeeoooooooooooow'); }) var Kitty = mongoose.model('Kitty', schema); var fizz = new Kitty; fizz.meow(); // meeeeeooooooooooooow
If a hash of name/fn pairs is passed as the only argument, each name/fn pair will be added as methods.
schema.method({ purr: function () {} , scratch: function () {} }); // later fizz.purr(); fizz.scratch();
Schema.prototype.method = function (name, fn) { if ('string' != typeof name) for (var i in name) this.methods[i] = name[i]; else this.methods[name] = fn; return this; };
Schema#path(
path
,constructor
)Gets/sets schema paths.
show codeSets a path (if arity 2)
Gets a path (if arity 1)Example
schema.path('name') // returns a SchemaType schema.path('name', Number) // changes the schemaType of `name` to Number
Schema.prototype.path = function (path, obj) { if (obj == undefined) { if (this.paths[path]) return this.paths[path]; if (this.subpaths[path]) return this.subpaths[path]; // subpaths? return /\.\d+\.?.*$/.test(path) ? getPositionalPath(this, path) : undefined; } // some path names conflict with document methods if (reserved[path]) { throw new Error("`" + path + "` may not be used as a schema pathname"); } // update the tree var subpaths = path.split(/\./) , last = subpaths.pop() , branch = this.tree; subpaths.forEach(function(sub, i) { if (!branch[sub]) branch[sub] = {}; if ('object' != typeof branch[sub]) { var msg = 'Cannot set nested path `' + path + '`. ' + 'Parent path `' + subpaths.slice(0, i).concat([sub]).join('.') + '` already set to type ' + branch[sub].name + '.'; throw new Error(msg); } branch = branch[sub]; }); branch[last] = utils.clone(obj); this.paths[path] = Schema.interpretAsType(path, obj); return this; };
Schema#pathType(
path
)Returns the pathType of
path
for this schema.Parameters:
path
<String>
Returns:
- <String>
show codeGiven a path, returns whether it is a real, virtual, nested, or ad-hoc/undefined path.
Schema.prototype.pathType = function (path) { if (path in this.paths) return 'real'; if (path in this.virtuals) return 'virtual'; if (path in this.nested) return 'nested'; if (path in this.subpaths) return 'real'; if (/\.\d+\.|\.\d+$/.test(path) && getPositionalPath(this, path)) { return 'real'; } else { return 'adhocOrUndefined' } };
Schema#plugin(
plugin
,opts
)Registers a plugin for this schema.
show codeSee:
Schema.prototype.plugin = function (fn, opts) { fn(this, opts); return this; };
Schema#post(
method
,fn
)Defines a post for the document
See:
show codePost hooks fire
on
the event emitted from document instances of Models compiled from this schema.var schema = new Schema(..); schema.post('save', function (doc) { console.log('this fired after a document was saved'); }); var Model = mongoose.model('Model', schema); var m = new Model(..); m.save(function (err) { console.log('this fires after the `post` hook'); });
Schema.prototype.post = function(method, fn){ return this.queue('on', arguments); };
Schema#pre(
method
,callback
)Defines a pre hook for the document.
See:
show codeExample
var toySchema = new Schema(..); toySchema.pre('save', function (next) { if (!this.created) this.created = new Date; next(); }) toySchema.pre('validate', function (next) { if (this.name != 'Woody') this.name = 'Woody'; next(); })
Schema.prototype.pre = function(){ return this.queue('pre', arguments); };
Schema#queue(
name
,args
)Adds a method call to the queue.
show codeParameters:
Schema.prototype.queue = function(name, args){ this.callQueue.push([name, args]); return this; };
Schema#requiredPaths()
Returns an Array of path strings that are required by this schema.
show codeReturns:
- <Array>
Schema.prototype.requiredPaths = function requiredPaths () { if (this._requiredpaths) return this._requiredpaths; var paths = Object.keys(this.paths) , i = paths.length , ret = []; while (i--) { var path = paths[i]; if (this.paths[path].isRequired) ret.push(path); } return this._requiredpaths = ret; }
Schema#set(
key
,[value]
)Sets/gets a schema option.
show codeParameters:
Schema.prototype.set = function (key, value, _tags) { if (1 === arguments.length) { return this.options[key]; } switch (key) { case 'read': this.options[key] = mquery.utils.readPref(value, _tags) break; case 'safe': this.options[key] = false === value ? { w: 0 } : value break; default: this.options[key] = value; } return this; }
Schema#static(
name
,fn
)Adds static "class" methods to Models compiled from this schema.
show codeExample
var schema = new Schema(..); schema.static('findByName', function (name, callback) { return this.find({ name: name }, callback); }); var Drink = mongoose.model('Drink', schema); Drink.findByName('sanpellegrino', function (err, drinks) { // });
If a hash of name/fn pairs is passed as the only argument, each name/fn pair will be added as statics.
Schema.prototype.static = function(name, fn) { if ('string' != typeof name) for (var i in name) this.statics[i] = name[i]; else this.statics[name] = fn; return this; };
Schema#virtual(
name
,[options]
)Creates a virtual type with the given name.
show codeReturns:
Schema.prototype.virtual = function (name, options) { var virtuals = this.virtuals; var parts = name.split('.'); return virtuals[name] = parts.reduce(function (mem, part, i) { mem[part] || (mem[part] = (i === parts.length-1) ? new VirtualType(options, name) : {}); return mem[part]; }, this.tree); };
Schema#virtualpath(
name
)Returns the virtual type with the given
name
.Parameters:
name
<String>
show codeReturns:
Schema.prototype.virtualpath = function (name) { return this.virtuals[name]; };
Schema.Types
The various built-in Mongoose Schema Types.
show codeSchema.Types = require('./schema/index');
Example:
var mongoose = require('mongoose'); var ObjectId = mongoose.Schema.Types.ObjectId;
Types:
Using this exposed access to the
Mixed
SchemaType, we can use them in our schema.var Mixed = mongoose.Schema.Types.Mixed; new mongoose.Schema({ _user: Mixed })
Schema.indexTypes()
The allowed index types
show codevar indexTypes = '2d 2dsphere hashed text'.split(' '); Object.defineProperty(Schema, 'indexTypes', { get: function () { return indexTypes } , set: function () { throw new Error('Cannot overwrite Schema.indexTypes') } })
Schema.interpretAsType(
path
,obj
)Converts type arguments into Mongoose Types.
show codeSchema.interpretAsType = function (path, obj) { if (obj.constructor && obj.constructor.name != 'Object') obj = { type: obj }; // Get the type making sure to allow keys named "type" // and default to mixed if not specified. // { type: { type: String, default: 'freshcut' } } var type = obj.type && !obj.type.type ? obj.type : {}; if ('Object' == type.constructor.name || 'mixed' == type) { return new Types.Mixed(path, obj); } if (Array.isArray(type) || Array == type || 'array' == type) { // if it was specified through { type } look for `cast` var cast = (Array == type || 'array' == type) ? obj.cast : type[0]; if (cast instanceof Schema) { return new Types.DocumentArray(path, cast, obj); } if ('string' == typeof cast) { cast = Types[cast.charAt(0).toUpperCase() + cast.substring(1)]; } else if (cast && (!cast.type || cast.type.type) && 'Object' == cast.constructor.name && Object.keys(cast).length) { return new Types.DocumentArray(path, new Schema(cast), obj); } return new Types.Array(path, cast || Types.Mixed, obj); } var name = 'string' == typeof type ? type : type.name; if (name) { name = name.charAt(0).toUpperCase() + name.substring(1); } if (undefined == Types[name]) { throw new TypeError('Undefined type at `' + path + '` Did you try nesting Schemas? ' + 'You can only nest using refs or arrays.'); } return new Types[name](path, obj); };
Schema.reserved
Reserved document keys.
show codeSchema.reserved = Object.create(null); var reserved = Schema.reserved; reserved.on = reserved.db = reserved.init = reserved.isNew = reserved.errors = reserved.schema = reserved.options = reserved.modelName = reserved.collection = reserved.toObject = reserved.emit = // EventEmitter reserved._events = // EventEmitter reserved._pres = reserved._posts = 1 // hooks.js
Keys in this object are names that are rejected in schema declarations b/c they conflict with mongoose functionality. Using these key name will throw an error.
on, emit, _events, db, init, isNew, errors, schema, options, modelName, collection, _pres, _posts, toObject
NOTE: Use of these terms as method names is permitted, but play at your own risk, as they may be existing mongoose document methods you are stomping on.
var schema = new Schema(..); schema.methods.init = function () {} // potentially breaking
Schema#paths
Schema as flat paths
Example:
show code{ '_id' : SchemaType, , 'nested.key' : SchemaType, }
Schema.prototype.paths;
Schema#tree
Schema as a tree
Example:
show code{ '_id' : ObjectId , 'nested' : { 'key' : String } }
Schema.prototype.tree;
- schemadefault.js
exports#system.profile
Default model for querying the system.profiles collection.
show codeexports['system.profile'] = new Schema({ ts: Date , info: String // deprecated , millis: Number , op: String , ns: String , query: Schema.Types.Mixed , updateobj: Schema.Types.Mixed , ntoreturn: Number , nreturned: Number , nscanned: Number , responseLength: Number , client: String , user: String , idhack: Boolean , scanAndOrder: Boolean , keyUpdates: Number , cursorid: Number }, { noVirtualId: true, noId: true });
- schematype.js
SchemaType(
path
,[options]
,[instance]
)SchemaType constructor
show codefunction SchemaType (path, options, instance) { this.path = path; this.instance = instance; this.validators = []; this.setters = []; this.getters = []; this.options = options; this._index = null; this.selected; for (var i in options) if (this[i] && 'function' == typeof this[i]) { // { unique: true, index: true } if ('index' == i && this._index) continue; var opts = Array.isArray(options[i]) ? options[i] : [options[i]]; this[i].apply(this, opts); } };
SchemaType#applyGetters(
value
,scope
)Applies getters to a value
show codeSchemaType.prototype.applyGetters = function (value, scope) { if (SchemaType._isRef(this, value, scope, true)) return value; var v = value , getters = this.getters , len = getters.length; if (!len) { return v; } while (len--) { v = getters[len].call(scope, v, this); } return v; };
SchemaType#applySetters(
value
,scope
,init
)Applies setters
show codeSchemaType.prototype.applySetters = function (value, scope, init, priorVal) { if (SchemaType._isRef(this, value, scope, init)) { return init ? value : this.cast(value, scope, init, priorVal); } var v = value , setters = this.setters , len = setters.length if (!len) { if (null === v || undefined === v) return v; return this.cast(v, scope, init, priorVal) } while (len--) { v = setters[len].call(scope, v, this); } if (null === v || undefined === v) return v; // do not cast until all setters are applied #665 v = this.cast(v, scope, init, priorVal); return v; };
SchemaType#default(
val
)Sets a default value for this SchemaType.
Parameters:
val
<Function, T> the default value
Returns:
show codeExample:
var schema = new Schema({ n: { type: Number, default: 10 }) var M = db.model('M', schema) var m = new M; 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:
// values are cast: var schema = new Schema({ aNumber: Number, default: "4.815162342" }) var M = db.model('M', schema) var m = new M; console.log(m.aNumber) // 4.815162342 // default unique objects for Mixed types: var schema = new Schema({ mixed: Schema.Types.Mixed }); schema.path('mixed').default(function () { return {}; }); // if we don't use a function to return object literals for Mixed defaults, // each document will receive a reference to the same object literal creating // a "shared" object instance: var schema = new Schema({ mixed: Schema.Types.Mixed }); schema.path('mixed').default({}); var M = db.model('M', schema); var m1 = new M; m1.mixed.added = 1; console.log(m1.mixed); // { added: 1 } var m2 = new M; console.log(m2.mixed); // { added: 1 }
SchemaType.prototype.default = function (val) { if (1 === arguments.length) { this.defaultValue = typeof val === 'function' ? val : this.cast(val); return this; } else if (arguments.length > 1) { this.defaultValue = utils.args(arguments); } return this.defaultValue; };
SchemaType#doValidate(
value
,callback
,scope
)Performs a validation of
show codevalue
using the validators declared for this SchemaType.SchemaType.prototype.doValidate = function (value, fn, scope) { var err = false , path = this.path , count = this.validators.length; if (!count) return fn(null); function validate (ok, message, type, val) { if (err) return; if (ok === undefined || ok) { --count || fn(null); } else { fn(err = new ValidatorError(path, message, type, val)); } } this.validators.forEach(function (v) { var validator = v[0] , message = v[1] , type = v[2]; if (validator instanceof RegExp) { validate(validator.test(value), message, type, value); } else if ('function' === typeof validator) { if (2 === validator.length) { validator.call(scope, value, function (ok) { validate(ok, message, type, value); }); } else { validate(validator.call(scope, value), message, type, value); } } }); };
SchemaType#get(
fn
)Adds a getter to this schematype.
Parameters:
fn
<Function>
Returns:
- <SchemaType> this
show codeExample:
function dob (val) { if (!val) return val; return (val.getMonth() + 1) + "/" + val.getDate() + "/" + val.getFullYear(); } // defining within the schema var s = new Schema({ born: { type: Date, get: dob }) // or by retreiving its SchemaType var s = new Schema({ born: Date }) 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:
function obfuscate (cc) { return '****-****-****-' + cc.slice(cc.length-4, cc.length); } var AccountSchema = new Schema({ creditCardNumber: { type: String, get: obfuscate } }); var Account = db.model('Account', AccountSchema); Account.findById(id, function (err, found) { console.log(found.creditCardNumber); // '****-****-****-1234' });
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.
function inspector (val, schematype) { if (schematype.options.required) { return schematype.path + ' is required'; } else { return schematype.path + ' is not'; } } var VirusSchema = new Schema({ name: { type: String, required: true, get: inspector }, taxonomy: { type: String, get: inspector } }) var Virus = db.model('Virus', VirusSchema); Virus.findById(id, function (err, virus) { console.log(virus.name); // name is required console.log(virus.taxonomy); // taxonomy is not })
SchemaType.prototype.get = function (fn) { if ('function' != typeof fn) throw new TypeError('A getter must be a function.'); this.getters.push(fn); return this; };
SchemaType#getDefault(
scope
,init
)Gets the default value
show codeSchemaType.prototype.getDefault = function (scope, init) { var ret = 'function' === typeof this.defaultValue ? this.defaultValue.call(scope) : this.defaultValue; if (null !== ret && undefined !== ret) { return this.cast(ret, scope, init); } else { return ret; } };
SchemaType#index(
options
)Declares the index options for this schematype.
Returns:
- <SchemaType> this
show codeExample:
var s = new Schema({ name: { type: String, index: true }) var s = new Schema({ loc: { type: [Number], index: 'hashed' }) var s = new Schema({ loc: { type: [Number], index: '2d', sparse: true }) var s = new Schema({ loc: { type: [Number], index: { type: '2dsphere', sparse: true }}) var s = new Schema({ date: { type: Date, index: { unique: true, expires: '1d' }}) Schema.path('my.path').index(true); Schema.path('my.date').index({ expires: 60 }); Schema.path('my.path').index({ unique: true, sparse: true });
NOTE:
Indexes are created in the background by default. Specify
background: false
to override.SchemaType.prototype.index = function (options) { this._index = options; utils.expires(this._index); return this; };
SchemaType#required(
required
,[message]
)Adds a required validator to this schematype.
Parameters:
Returns:
- <SchemaType> this
show codeExample:
var s = new Schema({ born: { type: Date, required: true }) // or with custom error message var s = new Schema({ born: { type: Date, required: '{PATH} is required!' }) // or through the path API Schema.path('name').required(true); // with custom error messaging Schema.path('name').required(true, 'grrr :( ');
SchemaType.prototype.required = function (required, message) { if (false === required) { this.validators = this.validators.filter(function (v) { return v[0] != this.requiredValidator; }, this); this.isRequired = false; return this; } var self = this; this.isRequired = true; this.requiredValidator = function (v) { // in here, `this` refers to the validating document. // no validation when this path wasn't selected in the query. if ('isSelected' in this && !this.isSelected(self.path) && !this.isModified(self.path)) return true; return self.checkRequired(v, this); } if ('string' == typeof required) { message = required; required = undefined; } var msg = message || errorMessages.general.required; this.validators.push([this.requiredValidator, msg, 'required']); return this; };
SchemaType#select(
val
)Sets default
select()
behavior for this path.Parameters:
val
<Boolean>
Returns:
- <SchemaType> this
show codeSet 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:
T = db.model('T', new Schema({ x: { type: String, select: true }})); T.find(..); // field x will always be selected .. // .. unless overridden; T.find().select('-x').exec(callback);
SchemaType.prototype.select = function select (val) { this.selected = !! val; return this; }
SchemaType#set(
fn
)Adds a setter to this schematype.
Parameters:
fn
<Function>
Returns:
- <SchemaType> this
show codeExample:
function capitalize (val) { if ('string' != typeof val) val = ''; return val.charAt(0).toUpperCase() + val.substring(1); } // defining within the schema var s = new Schema({ name: { type: String, set: capitalize }}) // or by retreiving its SchemaType var s = new Schema({ name: String }) 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.
function toLower (v) { return v.toLowerCase(); } var UserSchema = new Schema({ email: { type: String, set: toLower } }) var User = db.model('User', UserSchema) var user = new User({email: 'AVENUE@Q.COM'}) console.log(user.email); // 'avenue@q.com' // or var user = new User user.email = 'Avenue@Q.com' console.log(user.email) // 'avenue@q.com'
As you can see above, 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.
NOTE: we could have also just used the built-in
lowercase: true
SchemaType option instead of defining our own function.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.
function inspector (val, schematype) { if (schematype.options.required) { return schematype.path + ' is required'; } else { return val; } } var VirusSchema = new Schema({ name: { type: String, required: true, set: inspector }, taxonomy: { type: String, set: inspector } }) var Virus = db.model('Virus', VirusSchema); var v = new Virus({ name: 'Parvoviridae', taxonomy: 'Parvovirinae' }); console.log(v.name); // name is required console.log(v.taxonomy); // Parvovirinae
SchemaType.prototype.set = function (fn) { if ('function' != typeof fn) throw new TypeError('A setter must be a function.'); this.setters.push(fn); return this; };
SchemaType#sparse(
bool
)Declares a sparse index.
Parameters:
bool
<Boolean>
Returns:
- <SchemaType> this
show codeExample:
var s = new Schema({ name: { type: String, sparse: true }) Schema.path('name').index({ sparse: true });
SchemaType.prototype.sparse = function (bool) { if (null == this._index || 'boolean' == typeof this._index) { this._index = {}; } else if ('string' == typeof this._index) { this._index = { type: this._index }; } this._index.sparse = bool; return this; };
SchemaType#unique(
bool
)Declares an unique index.
Parameters:
bool
<Boolean>
Returns:
- <SchemaType> this
show codeExample:
var s = new Schema({ name: { type: String, unique: true }) Schema.path('name').index({ unique: true });
NOTE: violating the constraint returns an
E11000
error from MongoDB when saving, not a Mongoose validation error.SchemaType.prototype.unique = function (bool) { if (null == this._index || 'boolean' == typeof this._index) { this._index = {}; } else if ('string' == typeof this._index) { this._index = { type: this._index }; } this._index.unique = bool; return this; };
SchemaType#validate(
obj
,[errorMsg]
)Adds validator(s) for this document path.
Returns:
- <SchemaType> this
show codeValidators always receive the value to validate as their first argument and must return
Boolean
. Returningfalse
means validation failed.The error message argument is optional. If not passed, the default generic error message template will be used.
Examples:
// make sure every value is equal to "something" function validator (val) { return val == 'something'; } new Schema({ name: { type: String, validate: validator }}); // with a custom error message var custom = [validator, 'Uh oh, {PATH} does not equal "something".'] new Schema({ name: { type: String, validate: custom }}); // adding many validators at a time var many = [ { validator: validator, msg: 'uh oh' } , { validator: anotherValidator, msg: 'failed' } ] new Schema({ name: { type: String, validate: many }}); // or utilizing SchemaType methods directly: var schema = new Schema({ name: 'string' }); 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 baseic templating. There are a few other template keywords besides
{PATH}
and{VALUE}
too. To find out more, details are available hereAsynchronous 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
orfalse
to communicate either success or failure respectively.schema.path('name').validate(function (value, respond) { doStuff(value, function () { ... respond(false); // validation failed }) }, '{PATH} failed validation.');
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, anerror
event will be emitted on your Models associated db connection, passing the validation error object along.var conn = mongoose.createConnection(..); conn.on('error', handleError); var Product = conn.model('Product', yourSchema); var dvd = new Product(..); 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.// registering an error listener on the Model lets us handle errors more locally Product.on('error', handleError);
SchemaType.prototype.validate = function (obj, message) { if ('function' == typeof obj || obj && 'RegExp' === obj.constructor.name) { if (!message) message = errorMessages.general.default; this.validators.push([obj, message, 'user defined']); return this; } var i = arguments.length , arg while (i--) { arg = arguments[i]; if (!(arg && 'Object' == arg.constructor.name)) { var msg = 'Invalid validator. Received (' + typeof arg + ') ' + arg + '. See http://mongoosejs.com/docs/api.html#schematype_SchemaType-validate'; throw new Error(msg); } this.validate(arg.validator, arg.msg); } return this; };
SchemaType._isRef(
self
,value
,doc
,init
)Determines if value is a valid Reference.
show codeSchemaType._isRef = function (self, value, doc, init) { // fast path var ref = init && self.options && self.options.ref; if (!ref && doc && doc.$__fullPath) { // checks for // - this populated with adhoc model and no ref was set in schema OR // - setting / pushing values after population var path = doc.$__fullPath(self.path); var owner = doc.ownerDocument ? doc.ownerDocument() : doc; ref = owner.populated(path); } if (ref) { if (null == value) return true; if (!Buffer.isBuffer(value) && // buffers are objects too 'Binary' != value._bsontype // raw binary value from the db && utils.isObject(value) // might have deselected _id in population query ) { return true; } } return false; }
Parameters:
self
<SchemaType>value
<Object>doc
<Document>init
<Boolean>
Returns:
- <Boolean>
- types/array.js
MongooseArray#$__getAtomics()
Depopulates stored atomic operation values as necessary for direct insertion to MongoDB.
Returns:
- <Array>
If no atomics exist, we return all array values after conversion.
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.doc.array = [1,2,3]; var popped = doc.array.$pop(); console.log(popped); // 3 console.log(doc.array); // [1,2] // no affect popped = doc.array.$pop(); console.log(doc.array); // [1,2] doc.save(function (err) { if (err) return handleError(err); // we saved, now $pop works again popped = doc.array.$pop(); console.log(popped); // 2 console.log(doc.array); // [1] })
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.doc.array = [1,2,3]; var shifted = doc.array.$shift(); console.log(shifted); // 1 console.log(doc.array); // [2,3] // no affect shifted = doc.array.$shift(); console.log(doc.array); // [2,3] doc.save(function (err) { if (err) return handleError(err); // we saved, now $shift works again shifted = doc.array.$shift(); console.log(shifted ); // 2 console.log(doc.array); // [3] })
MongooseArray(
values
,path
,doc
)Mongoose Array constructor.
Inherits:
show codeNOTE:
Values always have to be passed to the constructor to initialize, otherwise
MongooseArray#push
will mark the array as modified.function MongooseArray (values, path, doc) { var arr = []; arr.push.apply(arr, values); arr.__proto__ = MongooseArray.prototype; arr._atomics = {}; arr.validators = []; arr._path = path; if (doc) { arr._parent = doc; arr._schema = doc.schema.path(path); } return arr; };
MongooseArray#_cast(
value
)Casts a member based on this arrays schema.
Parameters:
value
<T>
show codeReturns:
- <value> the casted value
MongooseArray.prototype._cast = function (value) { var owner = this._owner; var populated = false; var Model; if (this._parent) { // if a populated array, we must cast to the same model // instance as specified in the original query. if (!owner) { owner = this._owner = this._parent.ownerDocument ? this._parent.ownerDocument() : this._parent; } populated = owner.populated(this._path, true); } if (populated && null != value) { // cast to the populated Models schema var Model = populated.options.model; // only objects are permitted so we can safely assume that // non-objects are to be interpreted as _id if (Buffer.isBuffer(value) || value instanceof ObjectId || !utils.isObject(value)) { value = { _id: value }; } value = new Model(value); return this._schema.caster.cast(value, this._parent, true) } return this._schema.caster.cast(value, this._parent, false) }
MongooseArray#_markModified(
embeddedDoc
,embeddedPath
)Marks this array as modified.
Parameters:
embeddedDoc
<EmbeddedDocument> the embedded doc that invoked this method on the ArrayembeddedPath
<String> the path which changed in the embeddedDoc
show codeIf it bubbles up from an embedded document change, then it takes the following arguments (otherwise, takes 0 arguments)
MongooseArray.prototype._markModified = function (elem, embeddedPath) { var parent = this._parent , dirtyPath; if (parent) { dirtyPath = this._path; if (arguments.length) { if (null != embeddedPath) { // an embedded doc bubbled up the change dirtyPath = dirtyPath + '.' + this.indexOf(elem) + '.' + embeddedPath; } else { // directly set an index dirtyPath = dirtyPath + '.' + elem; } } parent.markModified(dirtyPath); } return this; };
MongooseArray#_registerAtomic(
op
,val
)Register an atomic operation with the parent.
show codeParameters:
op
<Array> operationval
<T>
MongooseArray.prototype._registerAtomic = function (op, val) { if ('$set' == op) { // $set takes precedence over all other ops. // mark entire array modified. this._atomics = { $set: val }; return this; } var atomics = this._atomics; // reset pop/shift after save if ('$pop' == op && !('$pop' in atomics)) { var self = this; this._parent.once('save', function () { self._popped = self._shifted = null; }); } // check for impossible $atomic combos (Mongo denies more than one // $atomic op on a single path if (this._atomics.$set || Object.keys(atomics).length && !(op in atomics)) { // a different op was previously registered. // save the entire thing. this._atomics = { $set: this }; return this; } if (op === '$pullAll' || op === '$pushAll' || op === '$addToSet') { atomics[op] || (atomics[op] = []); atomics[op] = atomics[op].concat(val); } else if (op === '$pullDocs') { var pullOp = atomics['$pull'] || (atomics['$pull'] = {}) , selector = pullOp['_id'] || (pullOp['_id'] = {'$in' : [] }); selector['$in'] = selector['$in'].concat(val); } else { atomics[op] = val; } return this; };
MongooseArray#addToSet(
[args...]
)Adds values to the array if not already present.
Parameters:
[args...]
<T>
Returns:
- <Array> the values that were added
show codeExample:
console.log(doc.array) // [2,3,4] var added = doc.array.addToSet(4,5); console.log(doc.array) // [2,3,4,5] console.log(added) // [5]
MongooseArray.prototype.addToSet = function addToSet () { var values = [].map.call(arguments, this._cast, this) , added = [] , type = values[0] instanceof EmbeddedDocument ? 'doc' : values[0] instanceof Date ? 'date' : ''; values.forEach(function (v) { var found; switch (type) { case 'doc': found = this.some(function(doc){ return doc.equals(v) }); break; case 'date': var val = +v; found = this.some(function(d){ return +d === val }); break; default: found = ~this.indexOf(v); } if (!found) { [].push.call(this, v); this._registerAtomic('$addToSet', v); this._markModified(); [].push.call(added, v); } }, this); return added; };
MongooseArray#hasAtomics()
Returns the number of pending atomic operations to send to the db for this array.
show codeReturns:
- <Number>
MongooseArray.prototype.hasAtomics = function hasAtomics () { if (!(this._atomics && 'Object' === this._atomics.constructor.name)) { return 0; } return Object.keys(this._atomics).length; }
MongooseArray#indexOf(
obj
)Return the index of
obj
or-1
if not found.Parameters:
obj
<Object> the item to look for
show codeReturns:
- <Number>
MongooseArray.prototype.indexOf = function indexOf (obj) { if (obj instanceof ObjectId) obj = obj.toString(); for (var i = 0, len = this.length; i < len; ++i) { if (obj == this[i]) return i; } return -1; };
MongooseArray#inspect()
Helper for console.log
show codeMongooseArray.prototype.inspect = function () { return '[' + this.map(function (doc) { return ' ' + doc; }) + ' ]'; };
MongooseArray#nonAtomicPush(
[args...]
)Pushes items to the array non-atomically.
Parameters:
[args...]
<T>
show codeNOTE:
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.prototype.nonAtomicPush = function () { var values = [].map.call(arguments, this._cast, this) , ret = [].push.apply(this, values); this._registerAtomic('$set', this); this._markModified(); return ret; };
MongooseArray#pop()
Wraps
Array#pop
with proper change tracking.show codeNote:
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.prototype.pop = function () { var ret = [].pop.call(this); this._registerAtomic('$set', this); this._markModified(); return ret; };
MongooseArray#pull(
[args...]
)Pulls items from the array atomically.
Parameters:
[args...]
<T>
See:
show codeExamples:
doc.array.pull(ObjectId) doc.array.pull({ _id: 'someId' }) doc.array.pull(36) doc.array.pull('tag 1', 'tag 2')
To remove a document from a subdocument array we may pass an object with a matching
_id
.doc.subdocs.push({ _id: 4815162342 }) doc.subdocs.pull({ _id: 4815162342 }) // removed
Or we may passing the _id directly and let mongoose take care of it.
doc.subdocs.push({ _id: 4815162342 }) doc.subdocs.pull(4815162342); // works
MongooseArray.prototype.pull = function () { var values = [].map.call(arguments, this._cast, this) , cur = this._parent.get(this._path) , i = cur.length , mem; while (i--) { mem = cur[i]; if (mem instanceof EmbeddedDocument) { if (values.some(function (v) { return v.equals(mem); } )) { [].splice.call(cur, i, 1); } } else if (~cur.indexOf.call(values, mem)) { [].splice.call(cur, i, 1); } } if (values[0] instanceof EmbeddedDocument) { this._registerAtomic('$pullDocs', values.map( function (v) { return v._id; } )); } else { this._registerAtomic('$pullAll', values); } this._markModified(); return this; };
MongooseArray#push(
[args...]
)Wraps
Array#push
with proper change tracking.show codeParameters:
[args...]
<Object>
MongooseArray.prototype.push = function () { var values = [].map.call(arguments, this._cast, this) , ret = [].push.apply(this, values); // $pushAll might be fibbed (could be $push). But it makes it easier to // handle what could have been $push, $pushAll combos this._registerAtomic('$pushAll', values); this._markModified(); return ret; };
MongooseArray#set()
Sets the casted
val
at indexi
and marks the array modified.Returns:
- <Array> this
show codeExample:
// given documents based on the following var Doc = mongoose.model('Doc', new Schema({ array: [Number] })); var doc = new Doc({ array: [2,3,4] }) console.log(doc.array) // [2,3,4] doc.array.set(1,"5"); console.log(doc.array); // [2,5,4] // properly cast to number doc.save() // the change is saved // VS not using array#set doc.array[1] = "5"; console.log(doc.array); // [2,"5",4] // no casting doc.save() // change is not saved
MongooseArray.prototype.set = function set (i, val) { this[i] = this._cast(val); this._markModified(i); return this; }
MongooseArray#shift()
Wraps
Array#shift
with proper change tracking.show codeExample:
doc.array = [2,3]; var res = doc.array.shift(); console.log(res) // 2 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.prototype.shift = function () { var ret = [].shift.call(this); this._registerAtomic('$set', this); this._markModified(); return ret; };
MongooseArray#sort()
Wraps
Array#sort
with proper change tracking.show codeNOTE:
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.prototype.sort = function () { var ret = [].sort.apply(this, arguments); this._registerAtomic('$set', this); this._markModified(); return ret; }
MongooseArray#splice()
Wraps
Array#splice
with proper change tracking and casting.show codeNote:
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.prototype.splice = function splice () { var ret, vals, i; if (arguments.length) { vals = []; for (i = 0; i < arguments.length; ++i) { vals[i] = i < 2 ? arguments[i] : this._cast(arguments[i]); } ret = [].splice.apply(this, vals); this._registerAtomic('$set', this); this._markModified(); } return ret; }
MongooseArray#toObject(
options
)Returns a native js Array.
Parameters:
options
<Object>
show codeReturns:
- <Array>
MongooseArray.prototype.toObject = function (options) { if (options && options.depopulate) { return this.map(function (doc) { return doc instanceof Document ? doc.toObject(options) : doc }); } return this.slice(); }
MongooseArray#unshift()
Wraps
Array#unshift
with proper change tracking.show codeNote:
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.prototype.unshift = function () { var values = [].map.call(arguments, this._cast, this); [].unshift.apply(this, values); this._registerAtomic('$set', this); this._markModified(); return this.length; };
MongooseArray#_atomics
Stores a queue of atomic operations to perform
show codeMongooseArray.prototype._atomics;
- types/buffer.js
MongooseBuffer(
value
,encode
,offset
)Mongoose Buffer constructor.
Inherits:
show codeValues always have to be passed to the constructor to initialize.
function MongooseBuffer (value, encode, offset) { var length = arguments.length; var val; if (0 === length || null === arguments[0] || undefined === arguments[0]) { val = 0; } else { val = value; } var encoding; var path; var doc; if (Array.isArray(encode)) { // internal casting path = encode[0]; doc = encode[1]; } else { encoding = encode; } var buf = new Buffer(val, encoding, offset); buf.__proto__ = MongooseBuffer.prototype; // make sure these internal props don't show up in Object.keys() Object.defineProperties(buf, { validators: { value: [] } , _path: { value: path } , _parent: { value: doc } }); if (doc && "string" === typeof path) { Object.defineProperty(buf, '_schema', { value: doc.schema.path(path) }); } buf._subtype = 0; return buf; };
MongooseBuffer#_markModified()
Marks this buffer as modified.
show codeMongooseBuffer.prototype._markModified = function () { var parent = this._parent; if (parent) { parent.markModified(this._path); } return this; };
MongooseBuffer#copy(
target
)Copies the buffer.
Parameters:
target
<Buffer>
Returns:
show codeNote:
Buffer#copy
does not marktarget
as modified so you must copy from aMongooseBuffer
for it to work as expected. This is a work around sincecopy
modifies the target, not this.MongooseBuffer.prototype.copy = function (target) { var ret = Buffer.prototype.copy.apply(this, arguments); if (target instanceof MongooseBuffer) { target._markModified(); } return ret; };
MongooseBuffer#equals(
other
)Determines if this buffer is equals to
other
bufferParameters:
other
<Buffer>
show codeReturns:
- <Boolean>
MongooseBuffer.prototype.equals = function (other) { if (!Buffer.isBuffer(other)) { return false; } if (this.length !== other.length) { return false; } for (var i = 0; i < this.length; ++i) { if (this[i] !== other[i]) return false; } return true; }
MongooseBuffer#subtype(
subtype
)Sets the subtype option and marks the buffer modified.
Parameters:
subtype
<Hex>
show codeSubTypes:
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_DEFINEDdoc.buffer.subtype(bson.BSON_BINARY_SUBTYPE_UUID);
MongooseBuffer.prototype.subtype = function (subtype) { if ('number' != typeof subtype) { throw new TypeError('Invalid subtype. Expected a number'); } if (this._subtype != subtype) { this._markModified(); } this._subtype = subtype; }
MongooseBuffer#toObject(
[subtype]
)Converts this buffer to its Binary type representation.
Parameters:
[subtype]
<Hex>
Returns:
- <Binary>
show codeSubTypes:
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_DEFINEDdoc.buffer.toObject(bson.BSON_BINARY_SUBTYPE_USER_DEFINED);
MongooseBuffer.prototype.toObject = function (options) { var subtype = 'number' == typeof options ? options : (this._subtype || 0); return new Binary(this, subtype); };
MongooseBuffer#write()
Writes the buffer.
show codeMongooseBuffer.prototype.write = function () { var written = Buffer.prototype.write.apply(this, arguments); if (written > 0) { this._markModified(); } return written; };
MongooseBuffer#_subtype
Default subtype for the Binary representing this Buffer
show codeMongooseBuffer.prototype._subtype;
- types/documentarray.js
MongooseDocumentArray(
values
,path
,doc
)DocumentArray constructor
Returns:
show codeInherits:
function MongooseDocumentArray (values, path, doc) { var arr = []; // Values always have to be passed to the constructor to initialize, since // otherwise MongooseArray#push will mark the array as modified to the parent. arr.push.apply(arr, values); arr.__proto__ = MongooseDocumentArray.prototype; arr._atomics = {}; arr.validators = []; arr._path = path; if (doc) { arr._parent = doc; arr._schema = doc.schema.path(path); doc.on('save', arr.notify('save')); doc.on('isNew', arr.notify('isNew')); } return arr; };
MongooseDocumentArray#_cast()
Overrides MongooseArray#cast
show codeMongooseDocumentArray.prototype._cast = function (value) { if (value instanceof this._schema.casterConstructor) { if (!(value.__parent && value.__parentArray)) { // value may have been created using array.create() value.__parent = this._parent; value.__parentArray = this; } return value; } // handle cast('string') or cast(ObjectId) etc. // only objects are permitted so we can safely assume that // non-objects are to be interpreted as _id if (Buffer.isBuffer(value) || value instanceof ObjectId || !utils.isObject(value)) { value = { _id: value }; } return new this._schema.casterConstructor(value, this); };
MongooseDocumentArray#create(
obj
)Creates a subdocument casted to this schema.
Parameters:
obj
<Object> the value to cast to this arrays SubDocument schema
show codeThis is the same subdocument constructor used for casting.
MongooseDocumentArray.prototype.create = function (obj) { return new this._schema.casterConstructor(obj); }
MongooseDocumentArray#id(
id
)Searches array items for the first document with a matching _id.
Returns:
- <EmbeddedDocument, null> the subdocuent or null if not found.
show codeExample:
var embeddedDoc = m.array.id(some_id);
MongooseDocumentArray.prototype.id = function (id) { var casted , sid , _id try { var casted_ = ObjectIdSchema.prototype.cast.call({}, id); if (casted_) casted = String(casted_); } catch (e) { casted = null; } for (var i = 0, l = this.length; i < l; i++) { _id = this[i].get('_id'); if (_id instanceof Document) { sid || (sid = String(id)); if (sid == _id._id) return this[i]; } else if (!(_id instanceof ObjectId)) { sid || (sid = String(id)); if (sid == _id) return this[i]; } else if (casted == _id) { return this[i]; } } return null; };
MongooseDocumentArray#inspect()
Helper for console.log
show codeMongooseDocumentArray.prototype.inspect = function () { return '[' + this.map(function (doc) { if (doc) { return doc.inspect ? doc.inspect() : util.inspect(doc) } return 'null' }).join(' ') + ']'; };
MongooseDocumentArray#notify(
event
)Creates a fn that notifies all child docs of
event
.Parameters:
event
<String>
show codeReturns:
- <Function>
MongooseDocumentArray.prototype.notify = function notify (event) { var self = this; return function notify (val) { var i = self.length; while (i--) { if (!self[i]) continue; self[i].emit(event, val); } } }
MongooseDocumentArray#toObject(
[options]
)Returns a native js Array of plain js objects
Parameters:
[options]
<Object> optional options to pass to each documents `toObject` method call during conversion
Returns:
- <Array>
show codeNOTE:
Each sub-document is converted to a plain object by calling its
#toObject
method.MongooseDocumentArray.prototype.toObject = function (options) { return this.map(function (doc) { return doc && doc.toObject(options) || null; }); };
- 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:
[path]
<String>
Returns:
- <String>
EmbeddedDocument(
obj
,parentArr
,skipId
)EmbeddedDocument constructor.
Parameters:
obj
<Object> js object returned from the dbparentArr
<MongooseDocumentArray> the parent array of this documentskipId
<Boolean>
show codeInherits:
function EmbeddedDocument (obj, parentArr, skipId, fields) { if (parentArr) { this.__parentArray = parentArr; this.__parent = parentArr._parent; } else { this.__parentArray = undefined; this.__parent = undefined; } Document.call(this, obj, fields, skipId); var self = this; this.on('isNew', function (val) { self.isNew = val; }); };
EmbeddedDocument#inspect()
Helper for console.log
show codeEmbeddedDocument.prototype.inspect = function () { return inspect(this.toObject()); };
EmbeddedDocument#invalidate(
path
,err
)Marks a path as invalid, causing validation to fail.
Parameters:
show codeReturns:
- <Boolean>
EmbeddedDocument.prototype.invalidate = function (path, err, val, first) { if (!this.__parent) { var msg = 'Unable to invalidate a subdocument that has not been added to an array.' throw new Error(msg); } var index = this.__parentArray.indexOf(this); var parentPath = this.__parentArray._path; var fullPath = [parentPath, index, path].join('.'); // sniffing arguments: // need to check if user passed a value to keep // our error message clean. if (2 < arguments.length) { this.__parent.invalidate(fullPath, err, val); } else { this.__parent.invalidate(fullPath, err); } if (first) this.$__.validationError = this.ownerDocument().$__.validationError; return true; }
EmbeddedDocument#markModified(
path
)Marks the embedded doc modified.
Parameters:
path
<String> the path which changed
show codeExample:
var doc = blogpost.comments.id(hexstring); doc.mixed.type = 'changed'; doc.markModified('mixed.type');
EmbeddedDocument.prototype.markModified = function (path) { if (!this.__parentArray) return; this.$__.activePaths.modify(path); if (this.isNew) { // Mark the WHOLE parent array as modified // if this is a new document (i.e., we are initializing // a document), this.__parentArray._markModified(); } else this.__parentArray._markModified(this, path); };
EmbeddedDocument#ownerDocument()
Returns the top level document of this sub-document.
show codeReturns:
- <Document>
EmbeddedDocument.prototype.ownerDocument = function () { if (this.$__.ownerDocument) { return this.$__.ownerDocument; } var parent = this.__parent; if (!parent) return this; while (parent.__parent) { parent = parent.__parent; } return this.$__.ownerDocument = parent; }
EmbeddedDocument#parent()
Returns this sub-documents parent document.
show codeEmbeddedDocument.prototype.parent = function () { return this.__parent; }
EmbeddedDocument#parentArray()
Returns this sub-documents parent array.
show codeEmbeddedDocument.prototype.parentArray = function () { return this.__parentArray; }
EmbeddedDocument#remove(
[fn]
)Removes the subdocument from its parent array.
show codeParameters:
[fn]
<Function>
EmbeddedDocument.prototype.remove = function (fn) { if (!this.__parentArray) return this; var _id; if (!this.willRemove) { _id = this._doc._id; if (!_id) { throw new Error('For your own good, Mongoose does not know ' + 'how to remove an EmbeddedDocument that has no _id'); } this.__parentArray.pull({ _id: _id }); this.willRemove = true; } if (fn) fn(null); return this; };
EmbeddedDocument#save(
[fn]
)Used as a stub for hooks.js
Parameters:
[fn]
<Function>
Returns:
- <EmbeddedDocument> this
show codeNOTE:
This is a no-op. Does not actually save the doc to the db.
EmbeddedDocument.prototype.save = function(fn) { if (fn) fn(null); return this; };
EmbeddedDocument#update()
Override #update method of parent documents.
show codeEmbeddedDocument.prototype.update = function () { throw new Error('The #update method is not available on EmbeddedDocuments'); }
- types/objectid.js
ObjectId.fromString(
str
)Creates an ObjectId from
show codestr
ObjectId.fromString;
Returns:
- <ObjectId>
ObjectId.toString(
oid
)Converts
show codeoid
to a string.ObjectId.toString;
Parameters:
oid
<ObjectId> ObjectId instance
Returns:
- <String>
- utils.js
exports.pluralization
Pluralization rules.
show codeexports.pluralization = [ [/(m)an$/gi, '$1en'], [/(pe)rson$/gi, '$1ople'], [/(child)$/gi, '$1ren'], [/^(ox)$/gi, '$1en'], [/(ax|test)is$/gi, '$1es'], [/(octop|vir)us$/gi, '$1i'], [/(alias|status)$/gi, '$1es'], [/(bu)s$/gi, '$1ses'], [/(buffal|tomat|potat)o$/gi, '$1oes'], [/([ti])um$/gi, '$1a'], [/sis$/gi, 'ses'], [/(?:([^f])fe|([lr])f)$/gi, '$1$2ves'], [/(hive)$/gi, '$1s'], [/([^aeiouy]|qu)y$/gi, '$1ies'], [/(x|ch|ss|sh)$/gi, '$1es'], [/(matr|vert|ind)ix|ex$/gi, '$1ices'], [/([m|l])ouse$/gi, '$1ice'], [/(quiz)$/gi, '$1zes'], [/s$/gi, 's'], [/([^a-z])$/, '$1'], [/$/gi, 's'] ]; var rules = exports.pluralization;
These rules are applied while processing the argument to
toCollectionName
.exports.uncountables
Uncountable words.
show codeexports.uncountables = [ 'advice', 'energy', 'excretion', 'digestion', 'cooperation', 'health', 'justice', 'labour', 'machinery', 'equipment', 'information', 'pollution', 'sewage', 'paper', 'money', 'species', 'series', 'rain', 'rice', 'fish', 'sheep', 'moose', 'deer', 'news', 'expertise', 'status', 'media' ]; var uncountables = exports.uncountables;
These words are applied while processing the argument to
toCollectionName
. - virtualtype.js
VirtualType()
VirtualType constructor
show codeThis is what mongoose uses to define virtual attributes via
Schema.prototype.virtual
.Example:
var fullname = schema.virtual('fullname'); fullname instanceof mongoose.VirtualType // true
function VirtualType (options, name) { this.path = name; this.getters = []; this.setters = []; this.options = options || {}; }
VirtualType#applyGetters(
value
,scope
)Applies getters to
value
using optionalscope
.show codeReturns:
- <T> the value after applying all getters
VirtualType.prototype.applyGetters = function (value, scope) { var v = value; for (var l = this.getters.length - 1; l >= 0; l--) { v = this.getters[l].call(scope, v, this); } return v; };
VirtualType#applySetters(
value
,scope
)Applies setters to
value
using optionalscope
.show codeReturns:
- <T> the value after applying all setters
VirtualType.prototype.applySetters = function (value, scope) { var v = value; for (var l = this.setters.length - 1; l >= 0; l--) { v = this.setters[l].call(scope, v, this); } return v; };
VirtualType#get(
fn
)Defines a getter.
Parameters:
fn
<Function>
Returns:
- <VirtualType> this
show codeExample:
var virtual = schema.virtual('fullname'); virtual.get(function () { return this.name.first + ' ' + this.name.last; });
VirtualType.prototype.get = function (fn) { this.getters.push(fn); return this; };
VirtualType#set(
fn
)Defines a setter.
Parameters:
fn
<Function>
Returns:
- <VirtualType> this
show codeExample:
var virtual = schema.virtual('fullname'); virtual.set(function (v) { var parts = v.split(' '); this.name.first = parts[0]; this.name.last = parts[1]; });
VirtualType.prototype.set = function (fn) { this.setters.push(fn); return this; };
- collection.js
Collection(
name
,conn
,opts
)Abstract Collection constructor
Parameters:
name
<String> name of the collectionconn
<Connection> A MongooseConnection instanceopts
<Object> optional collection options
show codeThis is the base class that drivers inherit from and implement.
function Collection (name, conn, opts) { if (undefined === opts) opts = {}; if (undefined === opts.capped) opts.capped = {}; opts.bufferCommands = undefined === opts.bufferCommands ? true : opts.bufferCommands; if ('number' == typeof opts.capped) { opts.capped = { size: opts.capped }; } this.opts = opts; this.name = name; this.conn = conn; this.queue = []; this.buffer = this.opts.bufferCommands; if (STATES.connected == this.conn.readyState) { this.onOpen(); } };
Collection#addQueue(
name
,args
)Queues a method for later execution when its
database connection opens.show codeParameters:
Collection.prototype.addQueue = function (name, args) { this.queue.push([name, args]); return this; };
Collection#doQueue()
Executes all queued methods and clears the queue.
show codeCollection.prototype.doQueue = function () { for (var i = 0, l = this.queue.length; i < l; i++){ this[this.queue[i][0]].apply(this, this.queue[i][1]); } this.queue = []; return this; };
Collection#ensureIndex()
Abstract method that drivers must implement.
show codeCollection.prototype.ensureIndex = function(){ throw new Error('Collection#ensureIndex unimplemented by driver'); };
Collection#find()
Abstract method that drivers must implement.
show codeCollection.prototype.find = function(){ throw new Error('Collection#find unimplemented by driver'); };
Collection#findAndModify()
Abstract method that drivers must implement.
show codeCollection.prototype.findAndModify = function(){ throw new Error('Collection#findAndModify unimplemented by driver'); };
Collection#findOne()
Abstract method that drivers must implement.
show codeCollection.prototype.findOne = function(){ throw new Error('Collection#findOne unimplemented by driver'); };
Collection#getIndexes()
Abstract method that drivers must implement.
show codeCollection.prototype.getIndexes = function(){ throw new Error('Collection#getIndexes unimplemented by driver'); };
Collection#insert()
Abstract method that drivers must implement.
show codeCollection.prototype.insert = function(){ throw new Error('Collection#insert unimplemented by driver'); };
Collection#mapReduce()
Abstract method that drivers must implement.
show codeCollection.prototype.mapReduce = function(){ throw new Error('Collection#mapReduce unimplemented by driver'); };
Collection#onClose()
Called when the database disconnects
show codeCollection.prototype.onClose = function () { if (this.opts.bufferCommands) { this.buffer = true; } };
Collection#onOpen()
Called when the database connects
show codeCollection.prototype.onOpen = function () { var self = this; this.buffer = false; self.doQueue(); };
Collection#save()
Abstract method that drivers must implement.
show codeCollection.prototype.save = function(){ throw new Error('Collection#save unimplemented by driver'); };
Collection#update()
Abstract method that drivers must implement.
show codeCollection.prototype.update = function(){ throw new Error('Collection#update unimplemented by driver'); };