mongoose 6.3.8 → 6.4.1

package/types/index.d.ts

@@ -5,9 +5,10 @@
 /// <reference path="./cursor.d.ts" />
 /// <reference path="./document.d.ts" />
 /// <reference path="./error.d.ts" />
+/// <reference path="./expressions.d.ts" />
 /// <reference path="./helpers.d.ts" />
 /// <reference path="./middlewares.d.ts" />
-/// <reference path="./indizes.d.ts" />
+/// <reference path="./indexes.d.ts" />
 /// <reference path="./models.d.ts" />
 /// <reference path="./mongooseoptions.d.ts" />
 /// <reference path="./pipelinestage.d.ts" />
@@ -19,6 +20,7 @@
 /// <reference path="./types.d.ts" />
 /// <reference path="./utility.d.ts" />
 /// <reference path="./validation.d.ts" />
+/// <reference path="./inferschematype.d.ts" />
 
 declare class NativeDate extends global.Date { }
 
@@ -61,10 +63,18 @@ declare module 'mongoose' {
   /* ! ignore */
   export type CompileModelOptions = { overwriteModels?: boolean, connection?: Connection };
 
+  export function model<TSchema extends Schema = any>(
+    name: string,
+    schema?: TSchema,
+    collection?: string,
+    options?: CompileModelOptions
+  ): Model<InferSchemaType<TSchema>, ObtainSchemaGeneric<TSchema, 'TQueryHelpers'>, ObtainSchemaGeneric<TSchema, 'TInstanceMethods'>, {}, TSchema> & ObtainSchemaGeneric<TSchema, 'TStaticMethods'>;
+
   export function model<T>(name: string, schema?: Schema<T, any, any> | Schema<T & Document, any, any>, collection?: string, options?: CompileModelOptions): Model<T>;
+
   export function model<T, U, TQueryHelpers = {}>(
     name: string,
-    schema?: Schema<T, U, {}, TQueryHelpers>,
+    schema?: Schema<T, any, TQueryHelpers>,
     collection?: string,
     options?: CompileModelOptions
   ): U;
@@ -72,6 +82,12 @@ declare module 'mongoose' {
   /** Returns an array of model names created on this instance of Mongoose. */
   export function modelNames(): Array<string>;
 
+  /**
+   * Overwrites the current driver used by this Mongoose instance. A driver is a
+   * Mongoose-specific interface that defines functions like `find()`.
+   */
+  export function setDriver(driver: any): Mongoose;
+
   /** The node-mongodb-native driver Mongoose uses. */
   export const mongo: typeof mongodb;
 
@@ -91,7 +107,16 @@ declare module 'mongoose' {
   export interface AnyObject {
     [k: string]: any
   }
-  export type Require_id<T> = T extends { _id?: any } ? (T & { _id: T['_id'] }) : (T & { _id: Types.ObjectId });
+
+  export type Require_id<T> = T extends { _id?: infer U }
+    ? U extends any
+      ? (T & { _id: Types.ObjectId })
+      : T & Required<{ _id: U }>
+    : T & { _id: Types.ObjectId };
+
+  export type RequireOnlyTypedId<T> = T extends { _id?: infer U; }
+    ? Required<{ _id: U }>
+    : { _id: Types.ObjectId };
 
   export type HydratedDocument<DocType, TMethodsAndOverrides = {}, TVirtuals = {}> = DocType extends Document ? Require_id<DocType> : (Document<unknown, any, DocType> & Require_id<DocType> & TVirtuals & TMethodsAndOverrides);
 
@@ -131,14 +156,20 @@ declare module 'mongoose' {
     ? Schema<Omit<DocType, keyof T1> & T1, DiscriminatorModel<T2, M>, T3 | TInstanceMethods, T4 | TQueryHelpers, T5 | TVirtuals>
     : Schema<DocType, M, TInstanceMethods, TQueryHelpers, TVirtuals>;
 
-  export class Schema<DocType = any, M = Model<DocType, any, any, any>, TInstanceMethods = {}, TQueryHelpers = {}, TVirtuals = any> extends events.EventEmitter {
+  type QueryResultType<T> = T extends Query<infer ResultType, any> ? ResultType : never;
+
+  export class Schema<EnforcedDocType = any, M = Model<EnforcedDocType, any, any, any>, TInstanceMethods = {}, TQueryHelpers = {}, TVirtuals = any,
+    TStaticMethods = {},
+    TPathTypeKey extends TypeKeyBaseType = DefaultTypeKey,
+    DocType extends ObtainDocumentType<DocType, EnforcedDocType, TPathTypeKey> = ObtainDocumentType<any, EnforcedDocType, TPathTypeKey>>
+    extends events.EventEmitter {
     /**
      * Create a new schema
      */
-    constructor(definition?: SchemaDefinition<SchemaDefinitionType<DocType>>, options?: SchemaOptions);
+    constructor(definition?: SchemaDefinition<SchemaDefinitionType<EnforcedDocType>> | DocType, options?: SchemaOptions<TPathTypeKey, DocType, TInstanceMethods, TQueryHelpers, TStaticMethods>);
 
     /** Adds key path / schema type pairs to this schema. */
-    add(obj: SchemaDefinition<SchemaDefinitionType<DocType>> | Schema, prefix?: string): this;
+    add(obj: SchemaDefinition<SchemaDefinitionType<EnforcedDocType>> | Schema, prefix?: string): this;
 
     /**
      * Array of child schemas (from document arrays and single nested subdocs)
@@ -193,7 +224,7 @@ declare module 'mongoose' {
     methods: { [F in keyof TInstanceMethods]: TInstanceMethods[F] } & AnyObject;
 
     /** The original object passed to the schema constructor */
-    obj: SchemaDefinition<SchemaDefinitionType<DocType>>;
+    obj: SchemaDefinition<SchemaDefinitionType<EnforcedDocType>>;
 
     /** Gets/sets schema paths. */
     path<ResultType extends SchemaType = SchemaType>(path: string): ResultType;
@@ -211,14 +242,14 @@ declare module 'mongoose' {
     plugin(fn: (schema: Schema<DocType>, opts?: any) => void, opts?: any): this;
 
     /** Defines a post hook for the model. */
-    post<T = HydratedDocument<DocType, TInstanceMethods>>(method: MongooseDocumentMiddleware | MongooseDocumentMiddleware[] | RegExp, fn: PostMiddlewareFunction<T>): this;
-    post<T = HydratedDocument<DocType, TInstanceMethods>>(method: MongooseDocumentMiddleware | MongooseDocumentMiddleware[] | RegExp, options: SchemaPostOptions, fn: PostMiddlewareFunction<T>): this;
-    post<T extends Query<any, any>>(method: MongooseQueryMiddleware | MongooseQueryMiddleware[] | string | RegExp, fn: PostMiddlewareFunction<T>): this;
-    post<T extends Query<any, any>>(method: MongooseQueryMiddleware | MongooseQueryMiddleware[] | string | RegExp, options: SchemaPostOptions, fn: PostMiddlewareFunction<T>): this;
-    post<T extends Aggregate<any>>(method: 'aggregate' | RegExp, fn: PostMiddlewareFunction<T, Array<any>>): this;
-    post<T extends Aggregate<any>>(method: 'aggregate' | RegExp, options: SchemaPostOptions, fn: PostMiddlewareFunction<T, Array<any>>): this;
-    post<T = M>(method: 'insertMany' | RegExp, fn: PostMiddlewareFunction<T>): this;
-    post<T = M>(method: 'insertMany' | RegExp, options: SchemaPostOptions, fn: PostMiddlewareFunction<T>): this;
+    post<T = HydratedDocument<DocType, TInstanceMethods>>(method: MongooseDocumentMiddleware | MongooseDocumentMiddleware[] | RegExp, fn: PostMiddlewareFunction<T, T>): this;
+    post<T = HydratedDocument<DocType, TInstanceMethods>>(method: MongooseDocumentMiddleware | MongooseDocumentMiddleware[] | RegExp, options: SchemaPostOptions, fn: PostMiddlewareFunction<T, T>): this;
+    post<T extends Query<any, any>>(method: MongooseQueryMiddleware | MongooseQueryMiddleware[] | string | RegExp, fn: PostMiddlewareFunction<T, QueryResultType<T>>): this;
+    post<T extends Query<any, any>>(method: MongooseQueryMiddleware | MongooseQueryMiddleware[] | string | RegExp, options: SchemaPostOptions, fn: PostMiddlewareFunction<T, QueryResultType<T>>): this;
+    post<T extends Aggregate<any>>(method: 'aggregate' | RegExp, fn: PostMiddlewareFunction<T, Array<AggregateExtract<T>>>): this;
+    post<T extends Aggregate<any>>(method: 'aggregate' | RegExp, options: SchemaPostOptions, fn: PostMiddlewareFunction<T, Array<AggregateExtract<T>>>): this;
+    post<T = M>(method: 'insertMany' | RegExp, fn: PostMiddlewareFunction<T, T>): this;
+    post<T = M>(method: 'insertMany' | RegExp, options: SchemaPostOptions, fn: PostMiddlewareFunction<T, T>): this;
 
     post<T = HydratedDocument<DocType, TInstanceMethods>>(method: MongooseDocumentMiddleware | MongooseDocumentMiddleware[] | RegExp, fn: ErrorHandlingMiddlewareFunction<T>): this;
     post<T = HydratedDocument<DocType, TInstanceMethods>>(method: MongooseDocumentMiddleware | MongooseDocumentMiddleware[] | RegExp, options: SchemaPostOptions, fn: ErrorHandlingMiddlewareFunction<T>): this;
@@ -414,22 +445,20 @@ declare module 'mongoose' {
     $min?: AnyKeys<TSchema> & AnyObject;
     $max?: AnyKeys<TSchema> & AnyObject;
     $mul?: AnyKeys<TSchema> & AnyObject;
-    $rename?: { [key: string]: string };
+    $rename?: Record<string, string>;
     $set?: AnyKeys<TSchema> & AnyObject;
     $setOnInsert?: AnyKeys<TSchema> & AnyObject;
     $unset?: AnyKeys<TSchema> & AnyObject;
 
     /** @see https://docs.mongodb.com/manual/reference/operator/update-array/ */
-    $addToSet?: AnyKeys<TSchema> & AnyObject;
+    $addToSet?: mongodb.SetFields<TSchema>;
     $pop?: AnyKeys<TSchema> & AnyObject;
-    $pull?: AnyKeys<TSchema> & AnyObject;
-    $push?: AnyKeys<TSchema> & AnyObject;
-    $pullAll?: AnyKeys<TSchema> & AnyObject;
+    $pull?: mongodb.PullOperator<TSchema>;
+    $push?: mongodb.PushOperator<TSchema>;
+    $pullAll?: mongodb.PullAllOperator<TSchema>;
 
     /** @see https://docs.mongodb.com/manual/reference/operator/update-bitwise/ */
-    $bit?: {
-      [key: string]: { [key in 'and' | 'or' | 'xor']?: number };
-    };
+    $bit?: Record<string, mongodb.NumericType>;
   };
 
   export type UpdateWithAggregationPipeline = UpdateAggregationStage[];

package/types/inferschematype.d.ts

@@ -0,0 +1,155 @@
+import { Schema, InferSchemaType, SchemaType, SchemaTypeOptions, TypeKeyBaseType } from 'mongoose';
+
+declare module 'mongoose' {
+  /**
+   * @summary Obtains document schema type.
+   * @description Obtains document schema type from document Definition OR returns enforced schema type if it's provided.
+   * @param {DocDefinition} DocDefinition A generic equals to the type of document definition "provided in as first parameter in Schema constructor".
+   * @param {EnforcedDocType} EnforcedDocType A generic type enforced by user "provided before schema constructor".
+   * @param {TypeKey} TypeKey A generic of literal string type.
+   */
+  type ObtainDocumentType<DocDefinition, EnforcedDocType = any, TypeKey extends TypeKeyBaseType = DefaultTypeKey> =
+    IsItRecordAndNotAny<EnforcedDocType> extends true ? EnforcedDocType : {
+      [K in keyof (RequiredPaths<DocDefinition> &
+      OptionalPaths<DocDefinition>)]: ObtainDocumentPathType<DocDefinition[K], TypeKey>;
+    };
+
+  /**
+   * @summary Obtains document schema type from Schema instance.
+   * @param {SchemaType} SchemaType A generic of schema type instance.
+   * @example
+   * const userSchema = new Schema({userName:String});
+   * type UserType = InferSchemaType<typeof userSchema>;
+   * // result
+   * type UserType = {userName?: string}
+   */
+  type InferSchemaType<SchemaType> = ObtainSchemaGeneric<SchemaType, 'DocType'> ;
+
+  /**
+   * @summary Obtains schema Generic type by using generic alias.
+   * @param {TSchema} TSchema A generic of schema type instance.
+   * @param {alias} alias Targeted generic alias.
+   */
+  type ObtainSchemaGeneric<TSchema, alias extends 'EnforcedDocType' | 'M' | 'TInstanceMethods' | 'TQueryHelpers' | 'TVirtuals' | 'TStaticMethods' | 'TPathTypeKey' | 'DocType'> =
+    TSchema extends Schema<infer EnforcedDocType, infer M, infer TInstanceMethods, infer TQueryHelpers, infer TVirtuals, infer TStaticMethods, infer TPathTypeKey, infer DocType>
+      ? {
+        EnforcedDocType: EnforcedDocType;
+        M: M;
+        TInstanceMethods: TInstanceMethods;
+        TQueryHelpers: TQueryHelpers;
+        TVirtuals: TVirtuals;
+        TStaticMethods: TStaticMethods;
+        TPathTypeKey: TPathTypeKey;
+        DocType: DocType;
+      }[alias]
+      : unknown;
+}
+/**
+ * @summary Checks if a type is "Record" or "any".
+ * @description It Helps to check if user has provided schema type "EnforcedDocType"
+ * @param {T} T A generic type to be checked.
+ * @returns true if {@link T} is Record OR false if {@link T} is of any type.
+ */
+type IsItRecordAndNotAny<T> = IfEquals<T, any, false, T extends Record<any, any> ? true : false>;
+
+/**
+ * @summary Checks if two types are identical.
+ * @param {T} T The first type to be compared with {@link U}.
+ * @param {U} U The seconde type to be compared with {@link T}.
+ * @param {Y} Y A type to be returned if {@link T} &  {@link U} are identical.
+ * @param {N} N A type to be returned if {@link T} &  {@link U} are not identical.
+ */
+type IfEquals<T, U, Y = true, N = false> =
+    (<G>() => G extends T ? 1 : 0) extends
+    (<G>() => G extends U ? 1 : 0) ? Y : N;
+
+/**
+ * @summary Required path base type.
+ * @description It helps to check whereas if a path is required OR optional.
+ */
+type RequiredPathBaseType = { required: true | [true, string | undefined] };
+
+/**
+ * @summary Path base type defined by using TypeKey
+ * @description It helps to check if a path is defined by TypeKey OR not.
+ * @param {TypeKey} TypeKey A literal string refers to path type property key.
+ */
+type PathWithTypePropertyBaseType<TypeKey extends TypeKeyBaseType> = { [k in TypeKey]: any };
+
+/**
+ * @summary A Utility to obtain schema's required path keys.
+ * @param {T} T A generic refers to document definition.
+ * @returns required paths keys of document definition.
+ */
+type RequiredPathKeys<T> = {
+  [K in keyof T]: T[K] extends RequiredPathBaseType ? IfEquals<T[K], any, never, K> : never;
+}[keyof T];
+
+/**
+ * @summary A Utility to obtain schema's required paths.
+ * @param {T} T A generic refers to document definition.
+ * @returns a record contains required paths with the corresponding type.
+ */
+type RequiredPaths<T> = {
+  [K in RequiredPathKeys<T>]: T[K];
+};
+
+/**
+ * @summary A Utility to obtain schema's optional path keys.
+ * @param {T} T A generic refers to document definition.
+ * @returns optional paths keys of document definition.
+ */
+type OptionalPathKeys<T> = {
+  [K in keyof T]: T[K] extends RequiredPathBaseType ? never : K;
+}[keyof T];
+
+/**
+ * @summary A Utility to obtain schema's optional paths.
+ * @param {T} T A generic refers to document definition.
+ * @returns a record contains optional paths with the corresponding type.
+ */
+type OptionalPaths<T> = {
+  [K in OptionalPathKeys<T>]?: T[K];
+};
+
+/**
+ * @summary Obtains schema Path type.
+ * @description Obtains Path type by calling {@link ResolvePathType} OR by calling {@link InferSchemaType} if path of schema type.
+ * @param {PathValueType} PathValueType Document definition path type.
+ * @param {TypeKey} TypeKey A generic refers to document definition.
+ */
+type ObtainDocumentPathType<PathValueType, TypeKey extends TypeKeyBaseType> = PathValueType extends Schema<any>
+  ? InferSchemaType<PathValueType>
+  : ResolvePathType<
+  PathValueType extends PathWithTypePropertyBaseType<TypeKey> ? PathValueType[TypeKey] : PathValueType,
+  PathValueType extends PathWithTypePropertyBaseType<TypeKey> ? Omit<PathValueType, TypeKey> : {}
+  >;
+
+/**
+ * @param {T} T A generic refers to string path enums.
+ * @returns Path enum values type as literal strings or string.
+ */
+type PathEnumOrString<T extends SchemaTypeOptions<string>['enum']> = T extends (infer E)[] ? E : T extends { values: any } ? PathEnumOrString<T['values']> : string;
+
+/**
+ * @summary Resolve path type by returning the corresponding type.
+ * @param {PathValueType} PathValueType Document definition path type.
+ * @param {Options} Options Document definition path options except path type.
+ * @returns Number, "Number" or "number" will be resolved to string type.
+ */
+type ResolvePathType<PathValueType, Options extends SchemaTypeOptions<PathValueType> = {}> =
+  PathValueType extends (infer Item)[] ? IfEquals<Item, never, any, ResolvePathType<Item>>[] :
+    PathValueType extends StringConstructor | 'string' | 'String' | typeof Schema.Types.String ? PathEnumOrString<Options['enum']> :
+      PathValueType extends NumberConstructor | 'number' | 'Number' | typeof Schema.Types.Number ? number :
+        PathValueType extends DateConstructor | 'date' | 'Date' | typeof Schema.Types.Date ? Date :
+          PathValueType extends typeof Buffer | 'buffer' | 'Buffer' | typeof Schema.Types.Buffer ? Buffer :
+            PathValueType extends BooleanConstructor | 'boolean' | 'Boolean' | typeof Schema.Types.Boolean ? boolean :
+              PathValueType extends 'objectId' | 'ObjectId' | typeof Schema.Types.ObjectId ? Schema.Types.ObjectId :
+                PathValueType extends 'decimal128' | 'Decimal128' | typeof Schema.Types.Decimal128 ? Schema.Types.Decimal128 :
+                  PathValueType extends MapConstructor ? Map<string, ResolvePathType<Options['of']>> :
+                    PathValueType extends ArrayConstructor ? any[] :
+                      PathValueType extends typeof Schema.Types.Mixed ? any:
+                        IfEquals<PathValueType, ObjectConstructor> extends true ? any:
+                          IfEquals<PathValueType, {}> extends true ? any:
+                            PathValueType extends typeof SchemaType ? PathValueType['prototype'] :
+                              unknown;

package/types/models.d.ts

@@ -114,12 +114,12 @@ declare module 'mongoose' {
   }
 
   const Model: Model<any>;
-  interface Model<T, TQueryHelpers = {}, TMethodsAndOverrides = {}, TVirtuals = {}> extends
+  interface Model<T, TQueryHelpers = {}, TMethodsAndOverrides = {}, TVirtuals = {}, TSchema = any> extends
     NodeJS.EventEmitter,
     AcceptsDiscriminator,
     IndexManager,
     SessionStarter {
-    new <DocType = AnyKeys<T> & AnyObject>(doc?: DocType, fields?: any | null, options?: boolean | AnyObject): HydratedDocument<T, TMethodsAndOverrides, TVirtuals>;
+    new <DocType = T>(doc?: DocType, fields?: any | null, options?: boolean | AnyObject): HydratedDocument<T, TMethodsAndOverrides, TVirtuals> & ObtainSchemaGeneric<TSchema, 'TStaticMethods'>;
 
     aggregate<R = any>(pipeline?: PipelineStage[], options?: mongodb.AggregateOptions, callback?: Callback<R[]>): Aggregate<Array<R>>;
     aggregate<R = any>(pipeline: PipelineStage[], callback?: Callback<R[]>): Aggregate<Array<R>>;
@@ -128,27 +128,27 @@ declare module 'mongoose' {
     base: Mongoose;
 
     /**
-     * If this is a discriminator model, `baseModelName` is the name of
-     * the base model.
-     */
+   * If this is a discriminator model, `baseModelName` is the name of
+   * the base model.
+   */
     baseModelName: string | undefined;
 
     /**
-     * Sends multiple `insertOne`, `updateOne`, `updateMany`, `replaceOne`,
-     * `deleteOne`, and/or `deleteMany` operations to the MongoDB server in one
-     * command. This is faster than sending multiple independent operations (e.g.
-     * if you use `create()`) because with `bulkWrite()` there is only one network
-     * round trip to the MongoDB server.
-     */
+   * Sends multiple `insertOne`, `updateOne`, `updateMany`, `replaceOne`,
+   * `deleteOne`, and/or `deleteMany` operations to the MongoDB server in one
+   * command. This is faster than sending multiple independent operations (e.g.
+   * if you use `create()`) because with `bulkWrite()` there is only one network
+   * round trip to the MongoDB server.
+   */
     bulkWrite(writes: Array<mongodb.AnyBulkWriteOperation>, options: mongodb.BulkWriteOptions & MongooseBulkWriteOptions, callback: Callback<mongodb.BulkWriteResult>): void;
     bulkWrite(writes: Array<mongodb.AnyBulkWriteOperation>, callback: Callback<mongodb.BulkWriteResult>): void;
     bulkWrite(writes: Array<mongodb.AnyBulkWriteOperation>, options?: mongodb.BulkWriteOptions & MongooseBulkWriteOptions): Promise<mongodb.BulkWriteResult>;
 
     /**
-     * Sends multiple `save()` calls in a single `bulkWrite()`. This is faster than
-     * sending multiple `save()` calls because with `bulkSave()` there is only one
-     * network round trip to the MongoDB server.
-     */
+   * Sends multiple `save()` calls in a single `bulkWrite()`. This is faster than
+   * sending multiple `save()` calls because with `bulkSave()` there is only one
+   * network round trip to the MongoDB server.
+   */
     bulkSave(documents: Array<Document>, options?: mongodb.BulkWriteOptions): Promise<mongodb.BulkWriteResult>;
 
     /** Collection the model uses. */
@@ -163,21 +163,17 @@ declare module 'mongoose' {
     countDocuments(callback?: Callback<number>): QueryWithHelpers<number, HydratedDocument<T, TMethodsAndOverrides, TVirtuals>, TQueryHelpers, T>;
 
     /** Creates a new document or documents */
-    create(docs: (AnyKeys<T> | AnyObject)[], options?: SaveOptions): Promise<HydratedDocument<T, TMethodsAndOverrides, TVirtuals>[]>;
-    create(docs: (AnyKeys<T> | AnyObject)[], callback: Callback<HydratedDocument<T, TMethodsAndOverrides, TVirtuals>[]>): void;
-    create(doc: AnyKeys<T> | AnyObject): Promise<HydratedDocument<T, TMethodsAndOverrides, TVirtuals>>;
-    create(doc: AnyKeys<T> | AnyObject, callback: Callback<HydratedDocument<T, TMethodsAndOverrides, TVirtuals>>): void;
-    create<DocContents = AnyKeys<T>>(docs: DocContents[], options?: SaveOptions): Promise<HydratedDocument<T, TMethodsAndOverrides, TVirtuals>[]>;
-    create<DocContents = AnyKeys<T>>(docs: DocContents[], callback: Callback<HydratedDocument<T, TMethodsAndOverrides, TVirtuals>[]>): void;
-    create<DocContents = AnyKeys<T>>(doc: DocContents): Promise<HydratedDocument<T, TMethodsAndOverrides, TVirtuals>>;
-    create<DocContents = AnyKeys<T>>(...docs: DocContents[]): Promise<HydratedDocument<T, TMethodsAndOverrides, TVirtuals>[]>;
-    create<DocContents = AnyKeys<T>>(doc: DocContents, callback: Callback<HydratedDocument<T, TMethodsAndOverrides, TVirtuals>>): void;
+    create<DocContents = T>(docs: Array<T | DocContents>, options?: SaveOptions): Promise<HydratedDocument<MergeType<MergeType<T, DocContents>, RequireOnlyTypedId<T>>, TMethodsAndOverrides, TVirtuals>[]>;
+    create<DocContents = T>(docs: Array<T | DocContents>, callback: Callback<HydratedDocument<MergeType<MergeType<T, DocContents>, RequireOnlyTypedId<T>>, TMethodsAndOverrides, TVirtuals>[]>): void;
+    create<DocContents = T>(doc: DocContents | T): Promise<HydratedDocument<MergeType<MergeType<T, DocContents>, RequireOnlyTypedId<T>>, TMethodsAndOverrides, TVirtuals>>;
+    create<DocContents = T>(...docs: Array<T | DocContents>): Promise<HydratedDocument<MergeType<MergeType<T, DocContents>, RequireOnlyTypedId<T>>, TMethodsAndOverrides, TVirtuals>[]>;
+    create<DocContents = T>(doc: T | DocContents, callback: Callback<HydratedDocument<MergeType<MergeType<T, DocContents>, RequireOnlyTypedId<T>>, TMethodsAndOverrides, TVirtuals>>): void;
 
     /**
-     * Create the collection for this model. By default, if no indexes are specified,
-     * mongoose will not create the collection for the model until any documents are
-     * created. Use this method to create the collection explicitly.
-     */
+   * Create the collection for this model. By default, if no indexes are specified,
+   * mongoose will not create the collection for the model until any documents are
+   * created. Use this method to create the collection explicitly.
+   */
     createCollection<T extends mongodb.Document>(options: mongodb.CreateCollectionOptions & Pick<SchemaOptions, 'expires'> | null, callback: Callback<mongodb.Collection<T>>): void;
     createCollection<T extends mongodb.Document>(callback: Callback<mongodb.Collection<T>>): void;
     createCollection<T extends mongodb.Document>(options?: mongodb.CreateCollectionOptions & Pick<SchemaOptions, 'expires'>): Promise<mongodb.Collection<T>>;
@@ -186,34 +182,34 @@ declare module 'mongoose' {
     db: Connection;
 
     /**
-     * Deletes all of the documents that match `conditions` from the collection.
-     * Behaves like `remove()`, but deletes all documents that match `conditions`
-     * regardless of the `single` option.
-     */
+   * Deletes all of the documents that match `conditions` from the collection.
+   * Behaves like `remove()`, but deletes all documents that match `conditions`
+   * regardless of the `single` option.
+   */
     deleteMany(filter?: FilterQuery<T>, options?: QueryOptions<T>, callback?: CallbackWithoutResult): QueryWithHelpers<mongodb.DeleteResult, HydratedDocument<T, TMethodsAndOverrides, TVirtuals>, TQueryHelpers, T>;
     deleteMany(filter: FilterQuery<T>, callback: CallbackWithoutResult): QueryWithHelpers<mongodb.DeleteResult, HydratedDocument<T, TMethodsAndOverrides, TVirtuals>, TQueryHelpers, T>;
     deleteMany(callback: CallbackWithoutResult): QueryWithHelpers<mongodb.DeleteResult, HydratedDocument<T, TMethodsAndOverrides, TVirtuals>, TQueryHelpers, T>;
 
     /**
-     * Deletes the first document that matches `conditions` from the collection.
-     * Behaves like `remove()`, but deletes at most one document regardless of the
-     * `single` option.
-     */
+   * Deletes the first document that matches `conditions` from the collection.
+   * Behaves like `remove()`, but deletes at most one document regardless of the
+   * `single` option.
+   */
     deleteOne(filter?: FilterQuery<T>, options?: QueryOptions<T>, callback?: CallbackWithoutResult): QueryWithHelpers<mongodb.DeleteResult, HydratedDocument<T, TMethodsAndOverrides, TVirtuals>, TQueryHelpers, T>;
     deleteOne(filter: FilterQuery<T>, callback: CallbackWithoutResult): QueryWithHelpers<mongodb.DeleteResult, HydratedDocument<T, TMethodsAndOverrides, TVirtuals>, TQueryHelpers, T>;
     deleteOne(callback: CallbackWithoutResult): QueryWithHelpers<mongodb.DeleteResult, HydratedDocument<T, TMethodsAndOverrides, TVirtuals>, TQueryHelpers, T>;
 
     /**
-     * Event emitter that reports any errors that occurred. Useful for global error
-     * handling.
-     */
+   * Event emitter that reports any errors that occurred. Useful for global error
+   * handling.
+   */
     events: NodeJS.EventEmitter;
 
     /**
-     * Finds a single document by its _id field. `findById(id)` is almost*
-     * equivalent to `findOne({ _id: id })`. If you want to query by a document's
-     * `_id`, use `findById()` instead of `findOne()`.
-     */
+   * Finds a single document by its _id field. `findById(id)` is almost*
+   * equivalent to `findOne({ _id: id })`. If you want to query by a document's
+   * `_id`, use `findById()` instead of `findOne()`.
+   */
     findById<ResultDoc = HydratedDocument<T, TMethodsAndOverrides, TVirtuals>>(
       id: any,
       projection?: ProjectionType<T> | null,
@@ -244,28 +240,37 @@ declare module 'mongoose' {
     ): QueryWithHelpers<ResultDoc | null, ResultDoc, TQueryHelpers, T>;
 
     /**
-     * Shortcut for creating a new Document from existing raw data, pre-saved in the DB.
-     * The document returned has no paths marked as modified initially.
-     */
+   * Shortcut for creating a new Document from existing raw data, pre-saved in the DB.
+   * The document returned has no paths marked as modified initially.
+   */
     hydrate(obj: any): HydratedDocument<T, TMethodsAndOverrides, TVirtuals>;
 
     /**
-     * This function is responsible for building [indexes](https://docs.mongodb.com/manual/indexes/),
-     * unless [`autoIndex`](http://mongoosejs.com/docs/guide.html#autoIndex) is turned off.
-     * Mongoose calls this function automatically when a model is created using
-     * [`mongoose.model()`](/docs/api.html#mongoose_Mongoose-model) or
-     * [`connection.model()`](/docs/api.html#connection_Connection-model), so you
-     * don't need to call it.
-     */
+   * This function is responsible for building [indexes](https://docs.mongodb.com/manual/indexes/),
+   * unless [`autoIndex`](http://mongoosejs.com/docs/guide.html#autoIndex) is turned off.
+   * Mongoose calls this function automatically when a model is created using
+   * [`mongoose.model()`](/docs/api.html#mongoose_Mongoose-model) or
+   * [`connection.model()`](/docs/api.html#connection_Connection-model), so you
+   * don't need to call it.
+   */
     init(callback?: CallbackWithoutResult): Promise<HydratedDocument<T, TMethodsAndOverrides, TVirtuals>>;
 
     /** Inserts one or more new documents as a single `insertMany` call to the MongoDB server. */
-    insertMany(docs: Array<AnyKeys<T> | AnyObject>, options: InsertManyOptions & { rawResult: true }): Promise<InsertManyResult<T>>;
-    insertMany(docs: Array<AnyKeys<T> | AnyObject>, options?: InsertManyOptions): Promise<Array<HydratedDocument<T, TMethodsAndOverrides, TVirtuals>>>;
-    insertMany(doc: AnyKeys<T> | AnyObject, options: InsertManyOptions & { rawResult: true }): Promise<InsertManyResult<T>>;
-    insertMany(doc: AnyKeys<T> | AnyObject, options?: InsertManyOptions): Promise<HydratedDocument<T, TMethodsAndOverrides, TVirtuals>[]>;
-    insertMany(doc: AnyKeys<T> | AnyObject, options?: InsertManyOptions, callback?: Callback<HydratedDocument<T, TMethodsAndOverrides, TVirtuals>[] | InsertManyResult<T>>): void;
-    insertMany(docs: Array<AnyKeys<T> | AnyObject>, options?: InsertManyOptions, callback?: Callback<Array<HydratedDocument<T, TMethodsAndOverrides, TVirtuals>> | InsertManyResult<T>>): void;
+    insertMany<DocContents = T>(docs: Array<DocContents | T>, options: InsertManyOptions & { lean: true; }, callback: Callback<Array<MergeType<MergeType<T, DocContents>, RequireOnlyTypedId<T>>>>): void;
+    insertMany<DocContents = T>(docs: Array<DocContents | T>, options: InsertManyOptions & { rawResult: true; }, callback: Callback<mongodb.InsertManyResult<T>>): void;
+    insertMany<DocContents = T>(docs: Array<DocContents | T>, callback: Callback<Array<HydratedDocument<MergeType<MergeType<T, DocContents>, RequireOnlyTypedId<T>>, TMethodsAndOverrides, TVirtuals>>>): void;
+    insertMany<DocContents = T>(doc: DocContents, options: InsertManyOptions & { lean: true; }, callback: Callback<Array<MergeType<MergeType<T, DocContents>, RequireOnlyTypedId<T>>>>): void;
+    insertMany<DocContents = T>(doc: DocContents, options: InsertManyOptions & { rawResult: true; }, callback: Callback<mongodb.InsertManyResult<T>>): void;
+    insertMany<DocContents = T>(doc: DocContents, options: InsertManyOptions & { lean?: false | undefined }, callback: Callback<Array<HydratedDocument<MergeType<MergeType<T, DocContents>, RequireOnlyTypedId<T>>, TMethodsAndOverrides, TVirtuals>>>): void;
+    insertMany<DocContents = T>(doc: DocContents, callback: Callback<Array<HydratedDocument<MergeType<MergeType<T, DocContents>, RequireOnlyTypedId<T>>, TMethodsAndOverrides, TVirtuals>>>): void;
+
+    insertMany<DocContents = T>(docs: Array<DocContents | T>, options: InsertManyOptions & { lean: true; }): Promise<Array<MergeType<MergeType<T, DocContents>, RequireOnlyTypedId<T>>>>;
+    insertMany<DocContents = T>(docs: Array<DocContents | T>, options: InsertManyOptions & { rawResult: true; }): Promise<mongodb.InsertManyResult<T>>;
+    insertMany<DocContents = T>(docs: Array<DocContents | T>): Promise<Array<HydratedDocument<MergeType<MergeType<T, DocContents>, RequireOnlyTypedId<T>>, TMethodsAndOverrides, TVirtuals>>>;
+    insertMany<DocContents = T>(doc: DocContents, options: InsertManyOptions & { lean: true; }): Promise<Array<MergeType<MergeType<T, DocContents>, RequireOnlyTypedId<T>>>>;
+    insertMany<DocContents = T>(doc: DocContents, options: InsertManyOptions & { rawResult: true; }): Promise<mongodb.InsertManyResult<T>>;
+    insertMany<DocContents = T>(doc: DocContents, options: InsertManyOptions): Promise<Array<HydratedDocument<MergeType<MergeType<T, DocContents>, RequireOnlyTypedId<T>>, TMethodsAndOverrides, TVirtuals>>>;
+    insertMany<DocContents = T>(doc: DocContents): Promise<Array<HydratedDocument<MergeType<MergeType<T, DocContents>, RequireOnlyTypedId<T>>, TMethodsAndOverrides, TVirtuals>>>;
 
     /** The name of the model */
     modelName: string;
@@ -301,21 +306,31 @@ declare module 'mongoose' {
     estimatedDocumentCount(options?: QueryOptions<T>, callback?: Callback<number>): QueryWithHelpers<number, HydratedDocument<T, TMethodsAndOverrides, TVirtuals>, TQueryHelpers, T>;
 
     /**
-     * Returns a document with its `_id` if at least one document exists in the database that matches
-     * the given `filter`, and `null` otherwise.
-     */
+   * Returns a document with its `_id` if at least one document exists in the database that matches
+   * the given `filter`, and `null` otherwise.
+   */
     exists(filter: FilterQuery<T>, callback: Callback<Pick<Document<T>, '_id'> | null>): QueryWithHelpers<Pick<Document<T>, '_id'> | null, HydratedDocument<T, TMethodsAndOverrides, TVirtuals>, TQueryHelpers, T>;
     exists(filter: FilterQuery<T>): QueryWithHelpers<Pick<Document<T>, '_id'> | null, HydratedDocument<T, TMethodsAndOverrides, TVirtuals>, TQueryHelpers, T>;
 
     /** Creates a `find` query: gets a list of documents that match `filter`. */
-    find<ResultDoc = HydratedDocument<T, TMethodsAndOverrides, TVirtuals>>(callback?: Callback<ResultDoc[]>): QueryWithHelpers<Array<ResultDoc>, ResultDoc, TQueryHelpers, T>;
     find<ResultDoc = HydratedDocument<T, TMethodsAndOverrides, TVirtuals>>(
       filter: FilterQuery<T>,
-      projection?: ProjectionType<T> | null,
-      callback?: Callback<ResultDoc[]>
+      projection?: ProjectionType<T> | null | undefined,
+      options?: QueryOptions<T> | null | undefined,
+      callback?: Callback<ResultDoc[]> | undefined
+    ): QueryWithHelpers<Array<ResultDoc>, ResultDoc, TQueryHelpers, T>;
+    find<ResultDoc = HydratedDocument<T, TMethodsAndOverrides, TVirtuals>>(
+      filter: FilterQuery<T>,
+      projection?: ProjectionType<T> | null | undefined,
+      callback?: Callback<ResultDoc[]> | undefined
+    ): QueryWithHelpers<Array<ResultDoc>, ResultDoc, TQueryHelpers, T>;
+    find<ResultDoc = HydratedDocument<T, TMethodsAndOverrides, TVirtuals>>(
+      filter: FilterQuery<T>,
+      callback?: Callback<ResultDoc[]> | undefined
+    ): QueryWithHelpers<Array<ResultDoc>, ResultDoc, TQueryHelpers, T>;
+    find<ResultDoc = HydratedDocument<T, TMethodsAndOverrides, TVirtuals>>(
+      callback?: Callback<ResultDoc[]> | undefined
     ): QueryWithHelpers<Array<ResultDoc>, ResultDoc, TQueryHelpers, T>;
-    find<ResultDoc = HydratedDocument<T, TMethodsAndOverrides, TVirtuals>>(filter: FilterQuery<T>, callback?: Callback<ResultDoc[]>): QueryWithHelpers<Array<ResultDoc>, ResultDoc, TQueryHelpers, T>;
-    find<ResultDoc = HydratedDocument<T, TMethodsAndOverrides, TVirtuals>>(filter: FilterQuery<T>, projection?: ProjectionType<T> | null, options?: QueryOptions<T> | null, callback?: Callback<ResultDoc[]>): QueryWithHelpers<Array<ResultDoc>, ResultDoc, TQueryHelpers, T>;
 
     /** Creates a `findByIdAndDelete` query, filtering by the given `_id`. */
     findByIdAndDelete<ResultDoc = HydratedDocument<T, TMethodsAndOverrides, TVirtuals>>(id?: mongodb.ObjectId | any, options?: QueryOptions<T> | null, callback?: (err: CallbackError, doc: ResultDoc | null, res: any) => void): QueryWithHelpers<ResultDoc | null, ResultDoc, TQueryHelpers, T>;
@@ -385,9 +400,9 @@ declare module 'mongoose' {
     schema: Schema<T>;
 
     /**
-     * @deprecated use `updateOne` or `updateMany` instead.
-     * Creates a `update` query: updates one or many documents that match `filter` with `update`, based on the `multi` option.
-     */
+   * @deprecated use `updateOne` or `updateMany` instead.
+   * Creates a `update` query: updates one or many documents that match `filter` with `update`, based on the `multi` option.
+   */
     update<ResultDoc = HydratedDocument<T, TMethodsAndOverrides, TVirtuals>>(
       filter?: FilterQuery<T>,
       update?: UpdateQuery<T> | UpdateWithAggregationPipeline,

package/types/mongooseoptions.d.ts

@@ -79,6 +79,14 @@ declare module 'mongoose' {
     | stream.Writable
     | ((collectionName: string, methodName: string, ...methodArgs: any[]) => void);
 
+    /**
+     * If `false`, it will change the `createdAt` field to be [`immutable: false`](https://mongoosejs.com/docs/api/schematype.html#schematype_SchemaType-immutable)
+     * which means you can update the `createdAt`.
+     *
+     * @default true
+     */
+    'timestamps.createdAt.immutable'?: boolean
+
     /** If set, attaches [maxTimeMS](https://docs.mongodb.com/manual/reference/operator/meta/maxTimeMS/) to every query */
     maxTimeMS?: number;