types: augment bson.ObjectId instead of adding on own type

fixes Automattic#12537

test/types/mongo.test.ts

@@ -1,4 +1,17 @@
 import * as mongoose from 'mongoose';
 import { expectType } from 'tsd';
+import * as bson from 'bson';
 
 import GridFSBucket = mongoose.mongo.GridFSBucket;
+
+function gh12537() {
+  const schema = new mongoose.Schema({ test: String });
+  const model = mongoose.model('Test', schema);
+
+  const doc = new model({});
+
+  const v = new bson.ObjectId('somehex');
+  expectType<string>(v._id.toHexString());
+
+  doc._id = new bson.ObjectId('somehex');
+}

types/augmentations.d.ts

@@ -0,0 +1,9 @@
+// the import below is said to be unused, but actually required so that types get merged and not overwritten
+import * as bson from 'bson';
+
+declare module 'bson' {
+  interface ObjectId {
+    /** Mongoose automatically adds a conveniency "_id" getter on the base ObjectId class */
+    _id: this;
+  }
+}

types/index.d.ts

@@ -22,6 +22,7 @@
 /// <reference path="./validation.d.ts" />
 /// <reference path="./inferschematype.d.ts" />
 /// <reference path="./virtuals.d.ts" />
+/// <reference path="./augmentations.d.ts" />
 
 declare class NativeDate extends global.Date { }
 

types/types.d.ts

@@ -80,7 +80,6 @@ declare module 'mongoose' {
     }
 
     class ObjectId extends mongodb.ObjectId {
-      _id: this;
     }
 
     class Subdocument<IdType = any> extends Document<IdType> {