update mongoose readme faq with issue from #12385

mongoose/README.md

@@ -5,22 +5,22 @@ Scenarios where the Typescript code is identical to plain Javascript code are om
 ### Table of Contents
 * [Mongoose Methods, Properties, Constructors](#mongoose-methods-properties-constructors)
 * [Creating and Saving Documents](#creating-and-saving-documents)
+* [Promises](#promises)
 * [Instance Methods, Virtual Properties](#instance-methods-and-virtual-properties)
 * [Static Methods](#static-methods)
 * [Plugins](#plugins)
-* [Promises](#promises)
-* [FAQ](#faq)
+* [FAQ and Common Mistakes](#faq-and-common-mistakes)
 
 #### Mongoose Methods, Properties, Constructors
 You can call methods from the mongoose instance using:
-```
+```typescript
 import * as mongoose from 'mongoose';
 var MyModel = mongoose.model(...);
 var MySchema: mongoose.Schema = new mongoose.Schema(...);
 ```
 
 Alternatively, you can import individual names and call them:
-```
+```typescript
 import {model, Schema} from 'mongoose';
 var MyModel = model(...);
 var MySchema: Schema = new Schema(...):
@@ -28,7 +28,7 @@ var MySchema: Schema = new Schema(...):
 [top](#mongoosejs-typescript-docs)
 
 #### Creating and Saving Documents
-```
+```typescript
 import {Document, model, Model, Schema} from 'mongoose';
 
 var UserSchema: Schema = new Schema({
@@ -62,8 +62,43 @@ UserModel.findOne({}, (err: any, user: IUser) => {
 ```
 [top](#mongoosejs-typescript-docs)
 
-#### Instance Methods and Virtual Properties
+#### Promises
+These definitions use `global.Promise` by default. If you would like to use mongoose's own mpromise
+definition (which is deprecated), you can install definitions for [mongoose-promise](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/mongoose-promise).
+
+If you'd like to use something other than `global.Promise`, you'll need to create a simple `.d.ts` file:
+```typescript
+// promise-bluebird.d.ts
+import * as Bluebird from 'bluebird';
+
+declare module 'mongoose' {
+  type Promise<T> = Bluebird<T>;
+}
+
+// promise-q.d.ts
+import * as Q from 'q';
+
+declare module 'mongoose' {
+  type Promise<T> = Q.Promise<T>;
+}
+
+// another-promise.d.ts
+...
 ```
+To use it, you will need to `/// <reference path="promise-bluebird.d.ts" />` in one of your source code files,
+or include the `.d.ts` file in your compile.
+
+To assign the new promise library in your code, you will need to use one of the following options (since
+Typescript does not allow assigning properties of imported modules):
+
+* `(<any>mongoose).Promise = YOUR_PROMISE;`
+* `require('mongoose').Promise = YOUR_PROMISE;`
+* `import mongoose = require('mongoose'); ... mongoose.Promise = YOUR_PROMISE;`
+
+[top](#mongoosejs-typescript-docs)
+
+#### Instance Methods and Virtual Properties
+```typescript
 import {Document, model, Model, Schema} from 'mongoose';
 
 var UserSchema: Schema = new Schema({
@@ -71,6 +106,7 @@ var UserSchema: Schema = new Schema({
 });
 
 UserSchema.methods.method1 = function () { return '' };
+
 UserSchema.virtual('nameInCaps').get(function () {
   return this.name.toUpperCase();
 });
@@ -80,8 +116,8 @@ UserSchema.virtual('nameInCaps').set(function (caps) {
 
 interface IUser extends Document {
   name: string;
-  nameInCaps: string;
   method1: () => string;
+  nameInCaps: string;
 }
 
 var UserModel: Model<IUser> = model<IUser>('User', UserSchema);
@@ -98,7 +134,7 @@ UserModel.findOne({}, (err: any, user: IUser) => {
 [top](#mongoosejs-typescript-docs)
 
 #### Static Methods
-```
+```typescript
 import {Document, model, Model, Schema} from 'mongoose';
 
 var UserSchema = new Schema({});
@@ -116,7 +152,7 @@ UserModel.static1();    // static methods are available
 
 #### Plugins
 To write definitions for plugins, extend the mongoose module and create a simple plugin module:
-```
+```typescript
 // plugin.d.ts
 declare module 'mongoose' {
   export interface PassportLocalDocument {...}
@@ -152,51 +188,51 @@ var UserModel: IUserModel<IUser> = model<IUser>('User', UserSchema);
 Full example for [Passport Local Mongoose](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/passport-local-mongoose/passport-local-mongoose.d.ts)<br>
 [top](#mongoosejs-typescript-docs)
 
-#### Promises
-These definitions use global.Promise by default. If you would like to use mongoose's own mpromise
-definition (which is deprecated), you can install definitions for [mongoose-promise](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/mongoose-promise).
-
-If you'd like to use something other than global.Promise, you'll need to create a simple .d.ts file:
+#### FAQ and Common Mistakes
+**Q: When to use `mongoose.Schema.Types.ObjectId` and `mongoose.Types.ObjectId`**<br>
+When creating schemas in code use `mongoose.Schema.Types.ObjectId`:
+```typescript
+var UserSchema = new mongoose.Schema({
+  id: mongoose.Schema.Types.ObjectId
+});
 ```
-// promise-bluebird.d.ts
-import * as Bluebird from 'bluebird';
-
-declare module 'mongoose' {
-  type Promise<T> = Bluebird<T>;
+Mongoose uses `mongoose.Schema.Types.ObjectId` internally to create the schema.
+However, if you define your interface like this:
+```typescript
+interface IUser extends mongoose.Document {
+  id: mongoose.Schema.Types.ObjectId;
 }
-
-// promise-q.d.ts
-import * as Q from 'q';
-
-declare module 'mongoose' {
-  type Promise<T> = Q.Promise<T>;
-}
-
-// another-promise.d.ts
 ...
+user.id = new mongoose.Types.ObjectId();
 ```
-To use it, you will need to `/// <reference path="promise-bluebird.d.ts" />` in one of your source code files,
-or include the `.d.ts` file in your compile.
+You are assigning a `mongoose.Types.ObjectId`, which is a different and incompatible type from
+`mongoose.Schema.Types.ObjectId`.
 
-To assign the new promise library in your code, you will need to use one of the following options (since
-Typescript does not allow assigning properties of imported modules):
+For proper type-checking, do this:
+```typescript
+interface IUser extends mongoose.Document {
+  id: mongoose.Types.ObjectId;     // for type-checking, doesn't affect code behaviour
+}
 
-* `(<any>mongoose).Promise = YOUR_PROMISE;`
-* `require('mongoose').Promise = YOUR_PROMISE;`
-* `import mongoose = require('mongoose'); ... mongoose.Promise = YOUR_PROMISE;`
+var UserSchema = new UserSchema({
+  id: mongoose.Schema.Types.ObjectId;   // for creating the schema only
+});
 
+var User = mongoose.model<IUser>('User', UserSchema);
+var user = new User({});
+user.id = new mongoose.Types.ObjectId();
+```
 [top](#mongoosejs-typescript-docs)
 
-#### FAQ
-Q: Why are there 2 interfaces for Documents called Document and MongooseDocument?<br>
-A: People have been using this for a long time:
-```
+**Q: Why are there 2 interfaces for Documents called Document and MongooseDocument?**<br>
+People have been using this for a long time:
+```typescript
 interface IUser extends mongoose.Document {
   ...
 }
 ```
 When it should really be this:
-```
+```typescript
 interface IUser extends mongoose.model {
   ...
 }