Merge pull request #12723 from Automattic/vkarpov15/gh-12595

feat(schema+types): add `{ errorHandler: true }` option to Schema `post()` for better TypeScript support

Author: vkarpov15

package.json

@@ -20,7 +20,7 @@
   "license": "MIT",
   "dependencies": {
     "bson": "^4.7.0",
-    "kareem": "2.4.1",
+    "kareem": "2.5.0",
     "mongodb": "4.12.1",
     "mpath": "0.9.0",
     "mquery": "4.0.3",

test/types/middleware.test.ts

@@ -135,3 +135,23 @@ function gh11480(): void {
     next();
   });
 }
+
+function gh12583() {
+  interface IUser {
+    name: string;
+    email: string;
+    avatar?: string;
+  }
+
+  const userSchema = new Schema<IUser>({
+    name: { type: String, required: true },
+    email: { type: String, required: true },
+    avatar: String
+  });
+
+  userSchema.post('save', { errorHandler: true }, function(error, doc, next) {
+    expectType<Error>(error);
+    console.log(error.name);
+    console.log(doc.name);
+  });
+}

types/index.d.ts

@@ -281,6 +281,11 @@ declare module 'mongoose' {
     plugin<PFunc extends PluginFunction<DocType, M, any, any, any, any>, POptions extends Parameters<PFunc>[1] = Parameters<PFunc>[1]>(fn: PFunc, opts?: POptions): this;
 
     /** Defines a post hook for the model. */
+    post<T = Query<any, any>>(method: MongooseQueryMiddleware | MongooseQueryMiddleware[] | RegExp, options: SchemaPostOptions & { errorHandler: true }, fn: ErrorHandlingMiddlewareWithOption<T>): this;
+    post<T = HydratedDocument<DocType, TInstanceMethods>>(method: MongooseDocumentMiddleware | MongooseDocumentMiddleware[] | RegExp, options: SchemaPostOptions & { errorHandler: true }, fn: ErrorHandlingMiddlewareWithOption<T>): this;
+    post<T extends Aggregate<any>>(method: 'aggregate' | RegExp, options: SchemaPostOptions & { errorHandler: true }, fn: ErrorHandlingMiddlewareWithOption<T, Array<any>>): this;
+    post<T = M>(method: 'insertMany' | RegExp, options: SchemaPostOptions & { errorHandler: true }, fn: ErrorHandlingMiddlewareWithOption<T>): this;
+
     post<T = Query<any, any>>(method: MongooseQueryMiddleware | MongooseQueryMiddleware[] | RegExp, fn: PostMiddlewareFunction<T, QueryResultType<T>>): this;
     post<T = Query<any, any>>(method: MongooseQueryMiddleware | MongooseQueryMiddleware[] | RegExp, options: SchemaPostOptions, fn: PostMiddlewareFunction<T, QueryResultType<T>>): this;
     post<T = HydratedDocument<DocType, TInstanceMethods>>(method: MongooseDocumentMiddleware | MongooseDocumentMiddleware[] | RegExp, fn: PostMiddlewareFunction<T, T>): this;

types/middlewares.d.ts

@@ -3,12 +3,29 @@ declare module 'mongoose' {
   type MongooseDocumentMiddleware = 'validate' | 'save' | 'remove' | 'updateOne' | 'deleteOne' | 'init';
   type MongooseQueryMiddleware = 'count' | 'estimatedDocumentCount' | 'countDocuments' | 'deleteMany' | 'deleteOne' | 'distinct' | 'find' | 'findOne' | 'findOneAndDelete' | 'findOneAndRemove' | 'findOneAndReplace' | 'findOneAndUpdate' | 'remove' | 'replaceOne' | 'update' | 'updateOne' | 'updateMany';
 
-  type MiddlewareOptions = { document?: boolean, query?: boolean };
+  type MiddlewareOptions = {
+    /**
+      * Enable this Hook for the Document Methods
+      * @default true
+      */
+    document?: boolean,
+    /**
+      * Enable this Hook for the Query Methods
+      * @default true
+      */
+    query?: boolean,
+    /**
+      * Explicitly set this function to be a Error handler instead of based on how many arguments are used
+      * @default false
+      */
+    errorHandler?: boolean
+  };
   type SchemaPreOptions = MiddlewareOptions;
   type SchemaPostOptions = MiddlewareOptions;
 
   type PreMiddlewareFunction<ThisType = any> = (this: ThisType, next: CallbackWithoutResultAndOptionalError) => void | Promise<void>;
   type PreSaveMiddlewareFunction<ThisType = any> = (this: ThisType, next: CallbackWithoutResultAndOptionalError, opts: SaveOptions) => void | Promise<void>;
   type PostMiddlewareFunction<ThisType = any, ResType = any> = (this: ThisType, res: ResType, next: CallbackWithoutResultAndOptionalError) => void | Promise<void>;
   type ErrorHandlingMiddlewareFunction<ThisType = any, ResType = any> = (this: ThisType, err: NativeError, res: ResType, next: CallbackWithoutResultAndOptionalError) => void;
+  type ErrorHandlingMiddlewareWithOption<ThisType = any, ResType = any> = (this: ThisType, err: NativeError, res: ResType | null, next: CallbackWithoutResultAndOptionalError) => void | Promise<void>;
 }