diff --git a/docs/guide.pug b/docs/guide.pug index 389be5cb92f..f80b4770314 100644 --- a/docs/guide.pug +++ b/docs/guide.pug @@ -81,8 +81,10 @@ block content Keys may also be assigned nested objects containing further key/type definitions like the `meta` property above. This will happen whenever a key's value is a POJO - that lacks a bona-fide `type` property. In these cases, only the leaves in a tree - are given actual paths in the schema (like `meta.votes` and `meta.favs` above), + that doesn't have a `type` property. + + In these cases, Mongoose only creates actual schema paths for leaves + in the tree. (like `meta.votes` and `meta.favs` above), and the branches do not have actual paths. A side-effect of this is that `meta` above cannot have its own validation. If validation is needed up the tree, a path needs to be created up the tree - see the [Subdocuments](./subdocs.html) section diff --git a/docs/index.pug b/docs/index.pug index 656c4db626f..c2b161fe421 100644 --- a/docs/index.pug +++ b/docs/index.pug @@ -31,7 +31,7 @@ block content ```javascript // getting-started.js - var mongoose = require('mongoose'); + const mongoose = require('mongoose'); mongoose.connect('mongodb://localhost/test', {useNewUrlParser: true}); ``` @@ -40,7 +40,7 @@ block content error occurs: ```javascript - var db = mongoose.connection; + const db = mongoose.connection; db.on('error', console.error.bind(console, 'connection error:')); db.once('open', function() { // we're connected! @@ -54,7 +54,7 @@ block content Let's get a reference to it and define our kittens. ```javascript - var kittySchema = new mongoose.Schema({ + const kittySchema = new mongoose.Schema({ name: String }); ``` @@ -62,7 +62,7 @@ block content So far so good. We've got a schema with one property, `name`, which will be a `String`. The next step is compiling our schema into a [Model](/docs/models.html). ```javascript - var Kitten = mongoose.model('Kitten', kittySchema); + const Kitten = mongoose.model('Kitten', kittySchema); ``` A model is a class with which we construct documents. @@ -70,7 +70,7 @@ block content Let's create a kitten document representing the little guy we just met on the sidewalk outside: ```javascript - var silence = new Kitten({ name: 'Silence' }); + const silence = new Kitten({ name: 'Silence' }); console.log(silence.name); // 'Silence' ``` @@ -80,20 +80,20 @@ block content ```javascript // NOTE: methods must be added to the schema before compiling it with mongoose.model() kittySchema.methods.speak = function () { - var greeting = this.name + const greeting = this.name ? "Meow name is " + this.name : "I don't have a name"; console.log(greeting); } - var Kitten = mongoose.model('Kitten', kittySchema); + const Kitten = mongoose.model('Kitten', kittySchema); ``` Functions added to the `methods` property of a schema get compiled into the `Model` prototype and exposed on each document instance: ```javascript - var fluffy = new Kitten({ name: 'fluffy' }); + const fluffy = new Kitten({ name: 'fluffy' }); fluffy.speak(); // "Meow name is fluffy" ``` diff --git a/docs/jest.pug b/docs/jest.pug index 2cb80547c36..16c5682b3c3 100644 --- a/docs/jest.pug +++ b/docs/jest.pug @@ -23,10 +23,11 @@ block content Jest is a client-side JavaScript testing library developed by Facebook. - It was one of the libraries affected by [Facebook's licensing scandal in 2017](https://www.theregister.co.uk/2017/09/22/facebook_will_free_react_other_code_from_unloved_license/). Because Jest is designed primarily for testing React applications, using it to test Node.js server-side applications comes with a lot of caveats. - We strongly recommend using [Mocha](http://npmjs.com/package/mocha) instead. + We strongly advise against using Jest for testing any Node.js apps unless + you are an expert developer with an intimate knowledge of Jest. + If you choose to delve into dangerous waters and test Mongoose apps with Jest, here's what you need to know: @@ -87,6 +88,14 @@ block content sinon.stub(time, 'setTimeout'); ``` + ## `globalSetup` and `globalTeardown` + + Do **not** use `globalSetup` to call `mongoose.connect()` or + `mongoose.createConnection()`. Jest runs `globalSetup` in + a [separate environment](https://github.com/facebook/jest/issues/7184), + so you cannot use any connections you create in `globalSetup` + in your tests. + ## Further Reading Want to learn more about testing Mongoose apps? The diff --git a/docs/models.pug b/docs/models.pug index f3cd5e8540f..b47da9b52b5 100644 --- a/docs/models.pug +++ b/docs/models.pug @@ -52,7 +52,7 @@ block content ``` :markdown The first argument is the _singular_ name of the collection your model is - for. ** Mongoose automatically looks for the plural, lowercased version of your model name. ** + for. **Mongoose automatically looks for the plural, lowercased version of your model name.** Thus, for the example above, the model Tank is for the **tanks** collection in the database. diff --git a/docs/schematypes.pug b/docs/schematypes.pug index 0e345936718..fc40f23da01 100644 --- a/docs/schematypes.pug +++ b/docs/schematypes.pug @@ -81,6 +81,7 @@ block content - [Array](#arrays) - [Decimal128](./api.html#mongoose_Mongoose-Decimal128) - [Map](#maps) + - [Schema](#schemas)

Example

@@ -662,6 +663,28 @@ block content schema.path('arr.0.url').get(v => `${root}${v}`); ``` +

Schemas

+ + To declare a path as another [schema](./guide.html#definition), + set `type` to the sub-schema's instance. + + To set a default value based on the sub-schema's shape, simply set a default value, + and the value will be cast based on the sub-schema's definition before being set + during document creation. + + ```javascript + const subSchema = new mongoose.Schema({ + // some schema definition here + }); + + const schema = new mongoose.Schema({ + data: { + type: subSchema + default: {} + } + }); + ``` +

Creating Custom Types

Mongoose can also be extended with [custom SchemaTypes](customschematypes.html). Search the diff --git a/docs/subdocs.pug b/docs/subdocs.pug index 78588429573..50b4c31b051 100644 --- a/docs/subdocs.pug +++ b/docs/subdocs.pug @@ -44,6 +44,7 @@ block content :markdown