feat: add afterOperation hook (#2697)

* feat: add afterOperation hook for Find operation

* docs: change #afterOperation to #afteroperation

* chore: extract afterOperation in function

* chore: implement afterChange in operations

* docs: use proper CollectionAfterOperationHook

* chore: remove outdated info

* chore: types afterOperation hook

* chore: improves afterOperation tests

* docs: updates description of afterOperation hook

* chore: improve typings

* chore: improve types

* chore: rename index.tsx => index.ts

---------

Co-authored-by: Jacob Fletcher <jacobsfletch@gmail.com>
Co-authored-by: Alessio Gravili <alessio@gravili.de>

Author: 3 people

docs/hooks/collections.mdx

@@ -16,6 +16,7 @@ Collections feature the ability to define the following hooks:
 - [afterRead](#afterread)
 - [beforeDelete](#beforedelete)
 - [afterDelete](#afterdelete)
+- [afterOperation](#afteroperation)
 
 Additionally, `auth`-enabled collections feature the following hooks:
 
@@ -31,6 +32,7 @@ Additionally, `auth`-enabled collections feature the following hooks:
 All collection Hook properties accept arrays of synchronous or asynchronous functions. Each Hook type receives specific arguments and has the ability to modify specific outputs.
 
 `collections/exampleHooks.js`
+
 ```ts
 import { CollectionConfig } from 'payload/types';
 
@@ -48,6 +50,7 @@ export const ExampleHooks: CollectionConfig = {
     afterChange: [(args) => {...}],
     afterRead: [(args) => {...}],
     afterDelete: [(args) => {...}],
+    afterOperation: [(args) => {...}],
 
     // Auth-enabled hooks
     beforeLogin: [(args) => {...}],
@@ -62,19 +65,19 @@ export const ExampleHooks: CollectionConfig = {
 
 ### beforeOperation
 
-The `beforeOperation` Hook type can be used to modify the arguments that operations accept or execute side-effects that run before an operation begins.
+The `beforeOperation` hook can be used to modify the arguments that operations accept or execute side-effects that run before an operation begins.
 
-Available Collection operations include `create`, `read`, `update`, `delete`, `login`, `refresh` and `forgotPassword`.
+Available Collection operations include `create`, `read`, `update`, `delete`, `login`, `refresh`, and `forgotPassword`.
 
 ```ts
-import { CollectionBeforeOperationHook } from 'payload/types';
+import { CollectionBeforeOperationHook } from "payload/types";
 
 const beforeOperationHook: CollectionBeforeOperationHook = async ({
-  args, // Original arguments passed into the operation
+  args, // original arguments passed into the operation
   operation, // name of the operation
 }) => {
-  return args; // Return operation arguments as necessary
-}
+  return args; // return modified operation arguments as necessary
+};
 ```
 
 ### beforeValidate
@@ -88,7 +91,7 @@ Please do note that this does not run before the client-side validation. If you
 3. `validate` runs on the server
 
 ```ts
-import { CollectionBeforeOperationHook } from 'payload/types';
+import { CollectionBeforeOperationHook } from "payload/types";
 
 const beforeValidateHook: CollectionBeforeValidateHook = async ({
   data, // incoming data to update or create with
@@ -97,15 +100,15 @@ const beforeValidateHook: CollectionBeforeValidateHook = async ({
   originalDoc, // original document
 }) => {
   return data; // Return data to either create or update a document with
-}
+};
 ```
 
 ### beforeChange
 
 Immediately following validation, `beforeChange` hooks will run within `create` and `update` operations. At this stage, you can be confident that the data that will be saved to the document is valid in accordance to your field validations. You can optionally modify the shape of data to be saved.
 
 ```ts
-import { CollectionBeforeChangeHook } from 'payload/types';
+import { CollectionBeforeChangeHook } from "payload/types";
 
 const beforeChangeHook: CollectionBeforeChangeHook = async ({
   data, // incoming data to update or create with
@@ -114,15 +117,15 @@ const beforeChangeHook: CollectionBeforeChangeHook = async ({
   originalDoc, // original document
 }) => {
   return data; // Return data to either create or update a document with
-}
+};
 ```
 
 ### afterChange
 
 After a document is created or updated, the `afterChange` hook runs. This hook is helpful to recalculate statistics such as total sales within a global, syncing user profile changes to a CRM, and more.
 
 ```ts
-import { CollectionAfterChangeHook } from 'payload/types';
+import { CollectionAfterChangeHook } from "payload/types";
 
 const afterChangeHook: CollectionAfterChangeHook = async ({
   doc, // full document data
@@ -131,31 +134,31 @@ const afterChangeHook: CollectionAfterChangeHook = async ({
   operation, // name of the operation ie. 'create', 'update'
 }) => {
   return doc;
-}
+};
 ```
 
 ### beforeRead
 
 Runs before `find` and `findByID` operations are transformed for output by `afterRead`. This hook fires before hidden fields are removed and before localized fields are flattened into the requested locale. Using this Hook will provide you with all locales and all hidden fields via the `doc` argument.
 
 ```ts
-import { CollectionBeforeReadHook } from 'payload/types';
+import { CollectionBeforeReadHook } from "payload/types";
 
 const beforeReadHook: CollectionBeforeReadHook = async ({
   doc, // full document data
   req, // full express request
   query, // JSON formatted query
 }) => {
   return doc;
-}
+};
 ```
 
 ### afterRead
 
 Runs as the last step before documents are returned. Flattens locales, hides protected fields, and removes fields that users do not have access to.
 
 ```ts
-import { CollectionAfterReadHook } from 'payload/types';
+import { CollectionAfterReadHook } from "payload/types";
 
 const afterReadHook: CollectionAfterReadHook = async ({
   doc, // full document data
@@ -164,7 +167,7 @@ const afterReadHook: CollectionAfterReadHook = async ({
   findMany, // boolean to denote if this hook is running against finding one, or finding many
 }) => {
   return doc;
-}
+};
 ```
 
 ### beforeDelete
@@ -194,19 +197,37 @@ const afterDeleteHook: CollectionAfterDeleteHook = async ({
 }) => {...}
 ```
 
+### afterOperation
+
+The `afterOperation` hook can be used to modify the result of operations or execute side-effects that run after an operation has completed.
+
+Available Collection operations include `create`, `find`, `findByID`, `update`, `updateByID`, `delete`, `deleteByID`, `login`, `refresh`, and `forgotPassword`.
+
+```ts
+import { CollectionAfterOperationHook } from "payload/types";
+
+const afterOperationHook: CollectionAfterOperationHook = async ({
+  args, // arguments passed into the operation
+  operation, // name of the operation
+  result, // the result of the operation, before modifications
+}) => {
+  return result; // return modified result as necessary
+};
+```
+
 ### beforeLogin
 
 For auth-enabled Collections, this hook runs during `login` operations where a user with the provided credentials exist, but before a token is generated and added to the response. You can optionally modify the user that is returned, or throw an error in order to deny the login operation.
 
 ```ts
-import { CollectionBeforeLoginHook } from 'payload/types';
+import { CollectionBeforeLoginHook } from "payload/types";
 
 const beforeLoginHook: CollectionBeforeLoginHook = async ({
   req, // full express request
   user, // user being logged in
 }) => {
   return user;
-}
+};
 ```
 
 ### afterLogin
@@ -267,15 +288,15 @@ const afterMeHook: CollectionAfterMeHook = async ({
 For auth-enabled Collections, this hook runs after successful `forgotPassword` operations. Returned values are discarded.
 
 ```ts
-import { CollectionAfterForgotPasswordHook } from 'payload/types';
+import { CollectionAfterForgotPasswordHook } from "payload/types";
 
 const afterLoginHook: CollectionAfterForgotPasswordHook = async ({
   req, // full express request
   user, // user being logged in
   token, // user token
 }) => {
   return user;
-}
+};
 ```
 
 ## TypeScript
@@ -298,5 +319,5 @@ import type {
   CollectionAfterRefreshHook,
   CollectionAfterMeHook,
   CollectionAfterForgotPasswordHook,
-} from 'payload/types';
+} from "payload/types";
 ```

src/auth/operations/forgotPassword.ts

@@ -3,6 +3,7 @@ import { Document } from 'mongoose';
 import { APIError } from '../../errors';
 import { PayloadRequest } from '../../express/types';
 import { Collection } from '../../collections/config/types';
+import { buildAfterOperation } from '../../collections/operations/utils';
 
 export type Arguments = {
   collection: Collection
@@ -128,6 +129,16 @@ async function forgotPassword(incomingArgs: Arguments): Promise<string | null> {
     await hook({ args, context: req.context });
   }, Promise.resolve());
 
+  // /////////////////////////////////////
+  // afterOperation - Collection
+  // /////////////////////////////////////
+
+  token = await buildAfterOperation({
+    operation: 'forgotPassword',
+    args,
+    result: token,
+  });
+
   return token;
 }
 

src/auth/operations/login.ts

@@ -10,6 +10,7 @@ import { User } from '../types';
 import { Collection } from '../../collections/config/types';
 import { afterRead } from '../../fields/hooks/afterRead';
 import unlock from './unlock';
+import { buildAfterOperation } from '../../collections/operations/utils';
 import { incrementLoginAttempts } from '../strategies/local/incrementLoginAttempts';
 import { authenticateLocalStrategy } from '../strategies/local/authenticate';
 import { getFieldsToSign } from './getFieldsToSign';
@@ -206,15 +207,28 @@ async function login<TSlug extends keyof GeneratedTypes['collections']>(
     }) || user;
   }, Promise.resolve());
 
-  // /////////////////////////////////////
-  // Return results
-  // /////////////////////////////////////
 
-  return {
+  let result: Result & { user: GeneratedTypes['collections'][TSlug] } = {
     token,
     user,
     exp: (jwt.decode(token) as jwt.JwtPayload).exp,
   };
+
+  // /////////////////////////////////////
+  // afterOperation - Collection
+  // /////////////////////////////////////
+
+  result = await buildAfterOperation<GeneratedTypes['collections'][TSlug]>({
+    operation: 'login',
+    args,
+    result,
+  });
+
+  // /////////////////////////////////////
+  // Return results
+  // /////////////////////////////////////
+
+  return result;
 }
 
 export default login;

src/auth/operations/refresh.ts

@@ -1,11 +1,12 @@
+import url from 'url';
 import jwt from 'jsonwebtoken';
 import { Response } from 'express';
-import url from 'url';
 import { Collection, BeforeOperationHook } from '../../collections/config/types';
 import { Forbidden } from '../../errors';
 import getCookieExpiration from '../../utilities/getCookieExpiration';
 import { Document } from '../../types';
 import { PayloadRequest } from '../../express/types';
+import { buildAfterOperation } from '../../collections/operations/utils';
 import { getFieldsToSign } from './getFieldsToSign';
 
 export type Result = {
@@ -97,7 +98,7 @@ async function refresh(incomingArgs: Arguments): Promise<Result> {
     args.res.cookie(`${config.cookiePrefix}-token`, refreshedToken, cookieOptions);
   }
 
-  let response: Result = {
+  let result: Result = {
     user,
     refreshedToken,
     exp,
@@ -110,20 +111,31 @@ async function refresh(incomingArgs: Arguments): Promise<Result> {
   await collectionConfig.hooks.afterRefresh.reduce(async (priorHook, hook) => {
     await priorHook;
 
-    response = (await hook({
+    result = (await hook({
       req: args.req,
       res: args.res,
       exp,
       token: refreshedToken,
       context: args.req.context,
-    })) || response;
+    })) || result;
   }, Promise.resolve());
 
+
+  // /////////////////////////////////////
+  // afterOperation - Collection
+  // /////////////////////////////////////
+
+  result = await buildAfterOperation({
+    operation: 'refresh',
+    args,
+    result,
+  });
+
   // /////////////////////////////////////
   // Return results
   // /////////////////////////////////////
 
-  return response;
+  return result;
 }
 
 export default refresh;

src/collections/config/defaults.ts

@@ -29,6 +29,7 @@ export const defaults = {
     afterRead: [],
     beforeDelete: [],
     afterDelete: [],
+    afterOperation: [],
     beforeLogin: [],
     afterLogin: [],
     afterLogout: [],

src/collections/config/schema.ts

@@ -98,6 +98,7 @@ const collectionSchema = joi.object().keys({
     afterRead: joi.array().items(joi.func()),
     beforeDelete: joi.array().items(joi.func()),
     afterDelete: joi.array().items(joi.func()),
+    afterOperation: joi.array().items(joi.func()),
     beforeLogin: joi.array().items(joi.func()),
     afterLogin: joi.array().items(joi.func()),
     afterLogout: joi.array().items(joi.func()),

src/collections/config/types.ts

@@ -12,6 +12,7 @@ import { IncomingUploadType, Upload } from '../../uploads/types';
 import { IncomingCollectionVersions, SanitizedCollectionVersions } from '../../versions/types';
 import { BuildQueryArgs } from '../../mongoose/buildQuery';
 import { CustomPreviewButtonProps, CustomPublishButtonProps, CustomSaveButtonProps, CustomSaveDraftButtonProps } from '../../admin/components/elements/types';
+import { AfterOperationArg, AfterOperationMap } from '../operations/utils';
 import type { Props as ListProps } from '../../admin/components/views/collections/List/types';
 import type { Props as EditProps } from '../../admin/components/views/collections/Edit/types';
 
@@ -123,6 +124,13 @@ export type AfterDeleteHook<T extends TypeWithID = any> = (args: {
   context: RequestContext;
 }) => any;
 
+
+export type AfterOperationHook<
+  T extends TypeWithID = any,
+> = (
+    arg: AfterOperationArg<T>,
+  ) => Promise<ReturnType<AfterOperationMap<T>[keyof AfterOperationMap<T>]>>;
+
 export type AfterErrorHook = (err: Error, res: unknown, context: RequestContext) => { response: any, status: number } | void;
 
 export type BeforeLoginHook<T extends TypeWithID = any> = (args: {
@@ -314,6 +322,7 @@ export type CollectionConfig = {
     afterMe?: AfterMeHook[];
     afterRefresh?: AfterRefreshHook[];
     afterForgotPassword?: AfterForgotPasswordHook[];
+    afterOperation?: AfterOperationHook[];
   };
   /**
    * Custom rest api endpoints