Merge branch 'master' into vkarpov15/gh-11257

CONTRIBUTING.md

@@ -58,7 +58,7 @@ If you'd like to preview your documentation changes, first commit your changes t
 * `npm install`
 * `npm run docs:view`
 
-Visit `http://localhost:8089` and you should see the docs with your local changes. Make sure you `npm run docs:clean` before committing, because automated generated files to `docs/*` should **not** be in PRs.
+Visit `http://127.0.0.1:8089` and you should see the docs with your local changes. Make sure you `npm run docs:clean` before committing, because automated generated files to `docs/*` should **not** be in PRs.
 
 #### Documentation Style Guidelines
 

README.md

@@ -66,7 +66,7 @@ const require = createRequire(import.meta.url);
 
 const mongoose = require('mongoose');
 
-mongoose.connect('mongodb://localhost:27017/test')
+mongoose.connect('mongodb://127.0.0.1:27017/test')
   .then(() => console.log('Connected!'));
 ```
 
@@ -91,12 +91,12 @@ First, we need to define a connection. If your app uses only one database, you s
 Both `connect` and `createConnection` take a `mongodb://` URI, or the parameters `host, database, port, options`.
 
 ```js
-await mongoose.connect('mongodb://localhost/my_database');
+await mongoose.connect('mongodb://127.0.0.1/my_database');
 ```
 
 Once connected, the `open` event is fired on the `Connection` instance. If you're using `mongoose.connect`, the `Connection` is `mongoose.connection`. Otherwise, `mongoose.createConnection` return value is a `Connection`.
 
-**Note:** _If the local connection fails then try using 127.0.0.1 instead of localhost. Sometimes issues may arise when the local hostname has been changed._
+**Note:** _If the local connection fails then try using 127.0.0.1 instead of 127.0.0.1. Sometimes issues may arise when the local hostname has been changed._
 
 **Important!** Mongoose buffers all the commands until it's connected to the database. This means that you don't have to wait until it connects to MongoDB in order to define models, run queries, etc.
 

benchmarks/benchjs/delete.js

@@ -17,11 +17,11 @@ const mongoClient = require('mongodb').MongoClient;
  * These are all the benchmark tests for deleting data
  */
 
-mongoose.connect('mongodb://localhost/mongoose-bench', function (err) {
+mongoose.connect('mongodb://127.0.0.1/mongoose-bench', function (err) {
   if (err) {
     throw err;
   }
-  mongoClient.connect('mongodb://localhost', function (err, client) {
+  mongoClient.connect('mongodb://127.0.0.1', function (err, client) {
     if (err) {
       throw err;
     }

benchmarks/benchjs/insert.js

@@ -19,12 +19,12 @@ const ObjectId = Schema.Types.ObjectId;
  * These are all the benchmark tests for inserting data
  */
 
-mongoose.connect('mongodb://localhost/mongoose-bench', function (err) {
+mongoose.connect('mongodb://127.0.0.1/mongoose-bench', function (err) {
   if (err) {
     throw err;
   }
   mongoClient.connect(
-    'mongodb://localhost/mongoose-bench',
+    'mongodb://127.0.0.1/mongoose-bench',
     function (err, client) {
       if (err) {
         throw err;

benchmarks/benchjs/multiop.js

@@ -19,11 +19,11 @@ const utils = require('../../lib/utils.js');
  * These are all the benchmark tests for mixed data operations
  */
 
-mongoose.connect('mongodb://localhost/mongoose-bench', function (err) {
+mongoose.connect('mongodb://127.0.0.1/mongoose-bench', function (err) {
   if (err) {
     throw err;
   }
-  mongoClient.connect('mongodb://localhost', function (err, client) {
+  mongoClient.connect('mongodb://127.0.0.1', function (err, client) {
     if (err) {
       throw err;
     }

benchmarks/benchjs/population.js

@@ -18,7 +18,7 @@ const utils = require('../../lib/utils.js');
  * These are all the benchmark tests for population ops
  */
 
-mongoose.connect('mongodb://localhost/mongoose-bench', function (err) {
+mongoose.connect('mongodb://127.0.0.1/mongoose-bench', function (err) {
   if (err) {
     throw err;
   }

benchmarks/benchjs/read.js

@@ -20,11 +20,11 @@ const utils = require('../../lib/utils.js');
  * These are all the benchmark tests for reading data
  */
 
-mongoose.connect('mongodb://localhost/mongoose-bench', function (err) {
+mongoose.connect('mongodb://127.0.0.1/mongoose-bench', function (err) {
   if (err) {
     throw err;
   }
-  mongoClient.connect('mongodb://localhost', function (err, client) {
+  mongoClient.connect('mongodb://127.0.0.1', function (err, client) {
     if (err) {
       throw err;
     }

benchmarks/benchjs/update.js

@@ -20,11 +20,11 @@ const utils = require('../../lib/utils.js');
  * These are all the benchmark tests for updating data
  */
 
-mongoose.connect('mongodb://localhost/mongoose-bench', function (err) {
+mongoose.connect('mongodb://127.0.0.1/mongoose-bench', function (err) {
   if (err) {
     throw err;
   }
-  mongoClient.connect('mongodb://localhost', function (err, client) {
+  mongoClient.connect('mongodb://127.0.0.1', function (err, client) {
     if (err) {
       throw err;
     }

benchmarks/mem.js

@@ -4,7 +4,7 @@ const mongoose = require('../');
 
 const Schema = mongoose.Schema;
 
-mongoose.connect('mongodb://localhost/mongoose-bench');
+mongoose.connect('mongodb://127.0.0.1/mongoose-bench');
 
 const DocSchema = new Schema({
   title: String

benchmarks/populate.js

@@ -18,7 +18,7 @@ const B = mongoose.model('B', Schema({
 let start;
 let count = 0;
 
-mongoose.connect('mongodb://localhost/mongoose-bench', function(err) {
+mongoose.connect('mongodb://127.0.0.1/mongoose-bench', function(err) {
   if (err) {
     return done(err);
   }

docs/connections.md

@@ -3,7 +3,7 @@
 You can connect to MongoDB with the `mongoose.connect()` method.
 
 ```javascript
-mongoose.connect('mongodb://localhost:27017/myapp');
+mongoose.connect('mongodb://127.0.0.1:27017/myapp');
 ```
 
 This is the minimum needed to connect the `myapp` database running locally
@@ -39,7 +39,7 @@ Mongoose lets you start using your models immediately, without waiting for
 mongoose to establish a connection to MongoDB.
 
 ```javascript
-mongoose.connect('mongodb://localhost:27017/myapp');
+mongoose.connect('mongodb://127.0.0.1:27017/myapp');
 const MyModel = mongoose.model('Test', new Schema({ name: String }));
 // Works
 MyModel.findOne(function(error, result) { /* ... */ });
@@ -56,7 +56,7 @@ const MyModel = mongoose.model('Test', new Schema({ name: String }));
 MyModel.findOne(function(error, result) { /* ... */ });
 
 setTimeout(function() {
-  mongoose.connect('mongodb://localhost:27017/myapp');
+  mongoose.connect('mongodb://127.0.0.1:27017/myapp');
 }, 60000);
 ```
 
@@ -101,12 +101,12 @@ There are two classes of errors that can occur with a Mongoose connection.
 To handle initial connection errors, you should use `.catch()` or `try/catch` with async/await.
 
 ```javascript
-mongoose.connect('mongodb://localhost:27017/test').
+mongoose.connect('mongodb://127.0.0.1:27017/test').
   catch(error => handleError(error));
 
 // Or:
 try {
-  await mongoose.connect('mongodb://localhost:27017/test');
+  await mongoose.connect('mongodb://127.0.0.1:27017/test');
 } catch (error) {
   handleError(error);
 }
@@ -201,9 +201,9 @@ driver. You **can't** set Mongoose-specific options like `bufferCommands`
 in the query string.
 
 ```javascript
-mongoose.connect('mongodb://localhost:27017/test?connectTimeoutMS=1000&bufferCommands=false&authSource=otherdb');
+mongoose.connect('mongodb://127.0.0.1:27017/test?connectTimeoutMS=1000&bufferCommands=false&authSource=otherdb');
 // The above is equivalent to:
-mongoose.connect('mongodb://localhost:27017/test', {
+mongoose.connect('mongodb://127.0.0.1:27017/test', {
   connectTimeoutMS: 1000
   // Note that mongoose will **not** pull `bufferCommands` from the query string
 });
@@ -453,7 +453,7 @@ using your connection options:
 mongoose.createConnection(uri, { maxPoolSize: 10 });
 
 // With connection string options
-const uri = 'mongodb://localhost:27017/test?maxPoolSize=10';
+const uri = 'mongodb://127.0.0.1:27017/test?maxPoolSize=10';
 mongoose.createConnection(uri);
 ```
 

docs/guide.md

@@ -274,9 +274,9 @@ While nice for development, it is recommended this behavior be disabled in produ
 Disable the behavior by setting the `autoIndex` option of your schema to `false`, or globally on the connection by setting the option `autoIndex` to `false`.
 
 ```javascript
-mongoose.connect('mongodb://user:pass@localhost:port/database', { autoIndex: false });
+mongoose.connect('mongodb://user:pass@127.0.0.1:port/database', { autoIndex: false });
 // or
-mongoose.createConnection('mongodb://user:pass@localhost:port/database', { autoIndex: false });
+mongoose.createConnection('mongodb://user:pass@127.0.0.1:port/database', { autoIndex: false });
 // or
 mongoose.set('autoIndex', false);
 // or

docs/index.md

@@ -32,9 +32,9 @@ const mongoose = require('mongoose');
 main().catch(err => console.log(err));
 
 async function main() {
-  await mongoose.connect('mongodb://localhost:27017/test');
+  await mongoose.connect('mongodb://127.0.0.1:27017/test');
 
-  // use `await mongoose.connect('mongodb://user:password@localhost:27017/test');` if your database has auth enabled
+  // use `await mongoose.connect('mongodb://user:password@127.0.0.1:27017/test');` if your database has auth enabled
 }
 ```
 

docs/middleware.md

@@ -206,7 +206,7 @@ error `err1` and then throw an error `err2`, mongoose will report `err1`.
 
 <h3 id="post"><a href="#post">Post middleware</a></h3>
 
-[post](schema.html#schema_Schema-post) middleware are executed _after_
+[post](api.html#schema_Schema-post) middleware are executed _after_
 the hooked method and all of its `pre` middleware have completed.
 
 ```javascript
@@ -334,8 +334,8 @@ doc.remove();
 Model.remove();
 ```
 
-You can pass options to [`Schema.pre()`](schema.html#schema_Schema-pre)
-and [`Schema.post()`](schema.html#schema_Schema-post) to switch whether
+You can pass options to [`Schema.pre()`](api.html#schema_Schema-pre)
+and [`Schema.post()`](api.html#schema_Schema-post) to switch whether
 Mongoose calls your `remove()` hook for [`Document.remove()`](model.html#model_Model-remove)
 or [`Model.remove()`](model.html#model_Model-remove). Note here that you need to set both `document` and `query` properties in the passed object:
 

docs/migrating_to_5.md

@@ -70,10 +70,10 @@ MyModel.find().exec(function() {
 // Worked in mongoose 4. Does **not** work in mongoose 5, `mongoose.connect()`
 // now returns a promise consistently. This is to avoid the horrible things
 // we've done to allow mongoose to be a thenable that resolves to itself.
-mongoose.connect('mongodb://localhost:27017/test').model('Test', new Schema({}));
+mongoose.connect('mongodb://127.0.0.1:27017/test').model('Test', new Schema({}));
 
 // Do this instead
-mongoose.connect('mongodb://localhost:27017/test');
+mongoose.connect('mongodb://127.0.0.1:27017/test');
 mongoose.model('Test', new Schema({}));
 ```
 
@@ -87,8 +87,8 @@ no longer supports several function signatures for `mongoose.connect()` that
 worked in Mongoose 4.x if the `useMongoClient` option was off. Below are some
 examples of `mongoose.connect()` calls that do **not** work in Mongoose 5.x.
 
-* `mongoose.connect('localhost', 27017);`
-* `mongoose.connect('localhost', 'mydb', 27017);`
+* `mongoose.connect('127.0.0.1', 27017);`
+* `mongoose.connect('127.0.0.1', 'mydb', 27017);`
 * `mongoose.connect('mongodb://host1:27017,mongodb://host2:27017');`
 
 In Mongoose 5.x, the first parameter to `mongoose.connect()` and `mongoose.createConnection()`, if specified, **must** be a [MongoDB connection string](https://docs.mongodb.com/manual/reference/connection-string/). The

docs/migrating_to_6.md

@@ -90,7 +90,7 @@ res.deletedCount; // Number of documents that were deleted. Replaces `res.n`
 // No longer necessary:
 mongoose.set('useFindAndModify', false);
 
-await mongoose.connect('mongodb://localhost:27017/test', {
+await mongoose.connect('mongodb://127.0.0.1:27017/test', {
   useNewUrlParser: true, // <-- no longer necessary
   useUnifiedTopology: true // <-- no longer necessary
 });

docs/models.md

@@ -64,13 +64,13 @@ uses is open. Every model has an associated connection. When you use
 `mongoose.model()`, your model will use the default mongoose connection.
 
 ```javascript
-mongoose.connect('mongodb://localhost/gettingstarted');
+mongoose.connect('mongodb://127.0.0.1/gettingstarted');
 ```
 
 If you create a custom connection, use that connection's `model()` function
 instead.
 ```javascript
-const connection = mongoose.createConnection('mongodb://localhost:27017/test');
+const connection = mongoose.createConnection('mongodb://127.0.0.1:27017/test');
 const Tank = connection.model('Tank', yourSchema);
 ```
 

docs/populate.md

@@ -444,8 +444,8 @@ Let's say you have a schema representing events, and a schema representing
 conversations. Each event has a corresponding conversation thread.
 
 ```javascript
-const db1 = mongoose.createConnection('mongodb://localhost:27000/db1');
-const db2 = mongoose.createConnection('mongodb://localhost:27001/db2');
+const db1 = mongoose.createConnection('mongodb://127.0.0.1:27000/db1');
+const db2 = mongoose.createConnection('mongodb://127.0.0.1:27001/db2');
 
 const conversationSchema = new Schema({ numMessages: Number });
 const Conversation = db2.model('Conversation', conversationSchema);

docs/queries.md

@@ -5,21 +5,21 @@ for [CRUD operations](https://en.wikipedia.org/wiki/Create,_read,_update_and_del
 Each of these functions returns a
 [mongoose `Query` object](query.html#Query).
 
-- [`Model.deleteMany()`](model.html#model_Model-deleteMany)
-- [`Model.deleteOne()`](model.html#model_Model-deleteOne)
-- [`Model.find()`](model.html#model_Model-find)
-- [`Model.findById()`](model.html#model_Model-findById)
-- [`Model.findByIdAndDelete()`](model.html#model_Model-findByIdAndDelete)
-- [`Model.findByIdAndRemove()`](model.html#model_Model-findByIdAndRemove)
-- [`Model.findByIdAndUpdate()`](model.html#model_Model-findByIdAndUpdate)
-- [`Model.findOne()`](model.html#model_Model-findOne)
-- [`Model.findOneAndDelete()`](model.html#model_Model-findOneAndDelete)
-- [`Model.findOneAndRemove()`](model.html#model_Model-findOneAndRemove)
-- [`Model.findOneAndReplace()`](model.html#model_Model-findOneAndReplace)
-- [`Model.findOneAndUpdate()`](model.html#model_Model-findOneAndUpdate)
-- [`Model.replaceOne()`](model.html#model_Model-replaceOne)
-- [`Model.updateMany()`](model.html#model_Model-updateMany)
-- [`Model.updateOne()`](model.html#model_Model-updateOne)
+- [`Model.deleteMany()`](api.html#model_Model-deleteMany)
+- [`Model.deleteOne()`](api.html#model_Model-deleteOne)
+- [`Model.find()`](api.html#model_Model-find)
+- [`Model.findById()`](api.html#model_Model-findById)
+- [`Model.findByIdAndDelete()`](api.html#model_Model-findByIdAndDelete)
+- [`Model.findByIdAndRemove()`](api.html#model_Model-findByIdAndRemove)
+- [`Model.findByIdAndUpdate()`](api.html#model_Model-findByIdAndUpdate)
+- [`Model.findOne()`](api.html#model_Model-findOne)
+- [`Model.findOneAndDelete()`](api.html#model_Model-findOneAndDelete)
+- [`Model.findOneAndRemove()`](api.html#model_Model-findOneAndRemove)
+- [`Model.findOneAndReplace()`](api.html#model_Model-findOneAndReplace)
+- [`Model.findOneAndUpdate()`](api.html#model_Model-findOneAndUpdate)
+- [`Model.replaceOne()`](api.html#model_Model-replaceOne)
+- [`Model.updateMany()`](api.html#model_Model-updateMany)
+- [`Model.updateOne()`](api.html#model_Model-updateOne)
 
 A mongoose query can be executed in one of two ways. First, if you
 pass in a `callback` function, Mongoose will execute the query asynchronously
@@ -57,7 +57,7 @@ will be null. If the query is successful, the `error` parameter will be null, an
 
 Anywhere a callback is passed to a query in Mongoose, the callback follows the pattern `callback(error, results)`.
 What `results` is depends on the operation: For `findOne()` it is a [potentially-null single document](api/model.html#model_Model-findOne), `find()` a [list of documents](api/model.html#model_Model-find), `count()` [the number of documents](api/model.html#model_Model-count), `update()` the [number of documents affected](api/model.html#model_Model-update), etc.
-The [API docs for Models](api/model-js.html#model-js) provide more detail on what is passed to the callbacks.
+The [API docs for Models](api/model.html) provide more detail on what is passed to the callbacks.
 
 Now let's look at what happens when no `callback` is passed:
 

docs/tutorials/getters-setters.md

@@ -70,6 +70,19 @@ below.
 [require:getters/setters.*setters.*update skip]
 ```
 
+## Passing Parameters using `$locals`
+
+You can't pass parameters to your getter and setter functions like you do to normal function calls.
+To configure or pass additional properties to your getters and setters, you can use the document's `$locals` property.
+
+The `$locals` property is the preferred place to store any program-defined data on your document without conflicting with schema-defined properties.
+In your getter and setter functions, `this` is the document being accessed, so you set properties on `$locals` and then access those properties in your getters examples.
+For example, the following shows how you can use `$locals` to configure the language for a custom getter that returns a string in different languages.
+
+```javascript
+[require:getters/setters.*localization.*locale]
+```
+
 Differences vs ES6 Getters/Setters
 ----------------------------------