types: make __v a number, only set __v on top-level documents

Re: #12959

test/types/document.test.ts

@@ -359,3 +359,19 @@ function gh13738() {
   expectType<Date>(person.get('dob'));
   expectType<{ theme: string; alerts: { sms: boolean } }>(person.get('settings'));
 }
+
+async function gh12959() {
+  const subdocSchema = new Schema({ foo: { type: 'string', required: true } });
+
+  const schema = new Schema({
+    subdocArray: { type: [subdocSchema], required: true },
+  });
+
+  const Model = model('test', schema);
+
+  const doc = await Model.findById('id').orFail();
+  expectType<Types.ObjectId>(doc._id);
+  expectType<number | undefined>(doc.__v);
+
+  expectError(doc.subdocArray[0].__v);
+}

types/document.d.ts

@@ -24,9 +24,6 @@ declare module 'mongoose' {
     /** This documents _id. */
     _id: T;
 
-    /** This documents __v. */
-    __v?: any;
-
     /** Assert that a given path or paths is populated. Throws an error if not populated. */
     $assertPopulated<Paths = {}>(path: string | string[], values?: Partial<Paths>): Omit<this, keyof Paths> & Paths;
 

types/index.d.ts

@@ -138,6 +138,10 @@ declare module 'mongoose' {
     ? IfAny<U, T & { _id: Types.ObjectId }, T & Required<{ _id: U }>>
     : T & { _id: Types.ObjectId };
 
+  export type Default__v<T> = T extends { __v?: infer U }
+    ? T
+    : T & { __v?: number };
+
   /** Helper type for getting the hydrated document type from the raw document type. The hydrated document type is what `new MyModel()` returns. */
   export type HydratedDocument<
     DocType,
@@ -147,12 +151,12 @@ declare module 'mongoose' {
     DocType,
     any,
     TOverrides extends Record<string, never> ?
-      Document<unknown, TQueryHelpers, DocType> & Require_id<DocType> :
+      Document<unknown, TQueryHelpers, DocType> & Default__v<Require_id<DocType>> :
       IfAny<
         TOverrides,
-        Document<unknown, TQueryHelpers, DocType> & Require_id<DocType>,
+        Document<unknown, TQueryHelpers, DocType> & Default__v<Require_id<DocType>>,
         Document<unknown, TQueryHelpers, DocType> & MergeType<
-          Require_id<DocType>,
+          Default__v<Require_id<DocType>>,
           TOverrides
         >
       >