feat: global beforeOperation hook (#13768)

Adds support for the `beforeOperation` hook on globals. Runs before all
other hooks to either modify the arguments that operations receive, or
perform side-effects before an operation begins.

```ts
import type { GlobalConfig } from 'payload'

const MyGlobal: GlobalConfig = {
  // ...
  hooks: {
    beforeOperation: []
  }
}
```

---
- To see the specific tasks where the Asana app for GitHub is being
used, see below:
  - https://app.asana.com/0/0/1211317005907890

docs/hooks/collections.mdx

@@ -67,8 +67,6 @@ export const CollectionWithHooks: CollectionConfig = {
 
 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`.
-
 ```ts
 import type { CollectionBeforeOperationHook } from 'payload'
 
@@ -83,12 +81,12 @@ const beforeOperationHook: CollectionBeforeOperationHook = async ({
 
 The following arguments are provided to the `beforeOperation` hook:
 
-| Option           | Description                                                                                                                                           |
+| Option           | Description                                                                                                                                                                                                                                                                               |
-| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **`collection`** | The [Collection](../configuration/collections) in which this Hook is running against.                                                                 |
+| **`collection`** | The [Collection](../configuration/collections) in which this Hook is running against. Available options include: `autosave`, `count`, `countVersions`, `create`, `delete`, `forgotPassword`, `login`, `read`, `readDistinct`, `refresh`, `resetPassword`, `restoreVersion`, and `update`. |
-| **`context`**    | Custom context passed between Hooks. [More details](./context).                                                                                       |
+| **`context`**    | Custom context passed between Hooks. [More details](./context).                                                                                                                                                                                                                           |
-| **`operation`**  | The name of the operation that this hook is running within.                                                                                           |
+| **`operation`**  | The name of the operation that this hook is running within.                                                                                                                                                                                                                               |
-| **`req`**        | The [Web Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object. This is mocked for [Local API](../local-api/overview) operations. |
+| **`req`**        | The [Web Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object. This is mocked for [Local API](../local-api/overview) operations.                                                                                                                                     |
 
 ### beforeValidate
 

docs/hooks/globals.mdx

@@ -38,6 +38,7 @@ const GlobalWithHooks: GlobalConfig = {
   // ...
   // highlight-start
   hooks: {
+    beforeOperation: [(args) => {...}],
     beforeValidate: [(args) => {...}],
     beforeChange: [(args) => {...}],
     beforeRead: [(args) => {...}],
@@ -48,6 +49,31 @@ const GlobalWithHooks: GlobalConfig = {
 }
 ```
 
+### beforeOperation
+
+The `beforeOperation` hook can be used to modify the arguments that operations accept or execute side-effects that run before an operation begins.
+
+```ts
+import type { GlobalBeforeOperationHook } from 'payload'
+
+const beforeOperationHook: GlobalBeforeOperationHook = async ({
+  args,
+  operation,
+  req,
+}) => {
+  return args // return modified operation arguments as necessary
+}
+```
+
+The following arguments are provided to the `beforeOperation` hook:
+
+| Option          | Description                                                                                                                                                         |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`global`**    | The [Global](../configuration/globals) in which this Hook is running against. Available operation include: `countVersions`, `read`, `restoreVersion`, and `update`. |
+| **`context`**   | Custom context passed between Hooks. [More details](./context).                                                                                                     |
+| **`operation`** | The name of the operation that this hook is running within.                                                                                                         |
+| **`req`**       | The [Web Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object. This is mocked for [Local API](../local-api/overview) operations.               |
+
 ### beforeValidate
 
 Runs during the `update` operation. This hook allows you to add or format data before the incoming data is validated server-side.

packages/payload/src/collections/config/types.ts

@@ -92,7 +92,9 @@ type CreateOrUpdateOperation = Extract<HookOperationType, 'create' | 'update'>
 
 export type BeforeOperationHook = (args: {
   args?: any
-  /** The collection which this hook is being run on */
+  /**
+   *  The collection which this hook is being run on
+   */
   collection: SanitizedCollectionConfig
   context: RequestContext
   /**

packages/payload/src/globals/config/sanitize.ts

@@ -24,6 +24,7 @@ export const sanitizeGlobal = async (
   if (global._sanitized) {
     return global as SanitizedGlobalConfig
   }
+
   global._sanitized = true
 
   global.label = global.label || toWords(global.slug)
@@ -33,12 +34,15 @@ export const sanitizeGlobal = async (
   // /////////////////////////////////
 
   global.endpoints = global.endpoints ?? []
+
   if (!global.hooks) {
     global.hooks = {}
   }
+
   if (!global.access) {
     global.access = {}
   }
+
   if (!global.admin) {
     global.admin = {}
   }
@@ -46,6 +50,7 @@ export const sanitizeGlobal = async (
   if (!global.access.read) {
     global.access.read = defaultAccess
   }
+
   if (!global.access.update) {
     global.access.update = defaultAccess
   }
@@ -53,15 +58,19 @@ export const sanitizeGlobal = async (
   if (!global.hooks.beforeValidate) {
     global.hooks.beforeValidate = []
   }
+
   if (!global.hooks.beforeChange) {
     global.hooks.beforeChange = []
   }
+
   if (!global.hooks.afterChange) {
     global.hooks.afterChange = []
   }
+
   if (!global.hooks.beforeRead) {
     global.hooks.beforeRead = []
   }
+
   if (!global.hooks.afterRead) {
     global.hooks.afterRead = []
   }

packages/payload/src/globals/config/types.ts

@@ -77,6 +77,22 @@ export type AfterReadHook = (args: {
   req: PayloadRequest
 }) => any
 
+export type HookOperationType = 'countVersions' | 'read' | 'restoreVersion' | 'update'
+
+export type BeforeOperationHook = (args: {
+  args?: any
+  context: RequestContext
+  /**
+   * The Global which this hook is being run on
+   * */
+  global: SanitizedGlobalConfig
+  /**
+   * Hook operation being performed
+   */
+  operation: HookOperationType
+  req: PayloadRequest
+}) => any
+
 export type GlobalAdminOptions = {
   /**
    * Custom admin components
@@ -187,6 +203,7 @@ export type GlobalConfig<TSlug extends GlobalSlug = any> = {
     afterChange?: AfterChangeHook[]
     afterRead?: AfterReadHook[]
     beforeChange?: BeforeChangeHook[]
+    beforeOperation?: BeforeOperationHook[]
     beforeRead?: BeforeReadHook[]
     beforeValidate?: BeforeValidateHook[]
   }

packages/payload/src/globals/operations/countGlobalVersions.ts

@@ -28,6 +28,23 @@ export const countGlobalVersionsOperation = async <TSlug extends GlobalSlug>(
     const req = args.req!
     const { payload } = req
 
+    // /////////////////////////////////////
+    // beforeOperation - Global
+    // /////////////////////////////////////
+
+    if (global.hooks?.beforeOperation?.length) {
+      for (const hook of global.hooks.beforeOperation) {
+        args =
+          (await hook({
+            args,
+            context: req.context,
+            global,
+            operation: 'countVersions',
+            req,
+          })) || args
+      }
+    }
+
     // /////////////////////////////////////
     // Access
     // /////////////////////////////////////

packages/payload/src/globals/operations/findOne.ts

@@ -52,6 +52,23 @@ export const findOneOperation = async <T extends Record<string, unknown>>(
   } = args
 
   try {
+    // /////////////////////////////////////
+    // beforeOperation - Global
+    // /////////////////////////////////////
+
+    if (globalConfig.hooks?.beforeOperation?.length) {
+      for (const hook of globalConfig.hooks.beforeOperation) {
+        args =
+          (await hook({
+            args,
+            context: args.req.context,
+            global: globalConfig,
+            operation: 'read',
+            req: args.req,
+          })) || args
+      }
+    }
+
     // /////////////////////////////////////
     // Retrieve and execute access
     // /////////////////////////////////////

packages/payload/src/globals/operations/restoreVersion.ts

@@ -31,6 +31,23 @@ export const restoreVersionOperation = async <T extends TypeWithVersion<T> = any
   try {
     const shouldCommit = await initTransaction(req)
 
+    // /////////////////////////////////////
+    // beforeOperation - Global
+    // /////////////////////////////////////
+
+    if (globalConfig.hooks?.beforeOperation?.length) {
+      for (const hook of globalConfig.hooks.beforeOperation) {
+        args =
+          (await hook({
+            args,
+            context: req.context,
+            global: globalConfig,
+            operation: 'restoreVersion',
+            req,
+          })) || args
+      }
+    }
+
     // /////////////////////////////////////
     // Access
     // /////////////////////////////////////

packages/payload/src/globals/operations/update.ts

@@ -77,6 +77,23 @@ export const updateOperation = async <
   try {
     const shouldCommit = !disableTransaction && (await initTransaction(req))
 
+    // /////////////////////////////////////
+    // beforeOperation - Global
+    // /////////////////////////////////////
+
+    if (globalConfig.hooks?.beforeOperation?.length) {
+      for (const hook of globalConfig.hooks.beforeOperation) {
+        args =
+          (await hook({
+            args,
+            context: args.req.context,
+            global: globalConfig,
+            operation: 'update',
+            req: args.req,
+          })) || args
+      }
+    }
+
     let { data } = args
 
     const shouldSaveDraft = Boolean(draftArg && globalConfig.versions?.drafts)

packages/payload/src/index.ts

@@ -1575,6 +1575,7 @@ export type {
   AfterChangeHook as GlobalAfterChangeHook,
   AfterReadHook as GlobalAfterReadHook,
   BeforeChangeHook as GlobalBeforeChangeHook,
+  BeforeOperationHook as GlobalBeforeOperationHook,
   BeforeReadHook as GlobalBeforeReadHook,
   BeforeValidateHook as GlobalBeforeValidateHook,
   DataFromGlobalSlug,

test/hooks/int.spec.ts

@@ -277,7 +277,7 @@ describe('Hooks', () => {
       const document = await payload.create({
         collection: contextHooksSlug,
         context: {
-          secretValue: 'data from local API',
+          secretValue: 'data from Local API',
         },
         data: {
           value: 'wrongvalue',
@@ -289,28 +289,28 @@ describe('Hooks', () => {
         collection: contextHooksSlug,
       })
 
-      expect(retrievedDoc.value).toEqual('data from local API')
+      expect(retrievedDoc.value).toEqual('data from Local API')
     })
 
-    it('should pass context from local API to global hooks', async () => {
+    it('should pass context from Local API to global hooks', async () => {
       const globalDocument = await payload.findGlobal({
         slug: dataHooksGlobalSlug,
       })
 
-      expect(globalDocument.field_globalAndField).not.toEqual('data from local API context')
+      expect(globalDocument.field_globalAndField).not.toEqual('data from Local API context')
 
       const globalDocumentWithContext = await payload.findGlobal({
         slug: dataHooksGlobalSlug,
         context: {
-          field_beforeChange_GlobalAndField_override: 'data from local API context',
+          field_beforeChange_GlobalAndField_override: 'data from Local API context',
         },
       })
-      expect(globalDocumentWithContext.field_globalAndField).toEqual('data from local API context')
+      expect(globalDocumentWithContext.field_globalAndField).toEqual('data from Local API context')
     })
 
-    it('should pass context from rest API to hooks', async () => {
+    it('should pass context from REST API to hooks', async () => {
       const params = new URLSearchParams({
-        context_secretValue: 'data from rest API',
+        context_secretValue: 'data from REST API',
       })
       // send context as query params. It will be parsed by the beforeOperation hook
       const { doc } = await restClient
@@ -326,7 +326,7 @@ describe('Hooks', () => {
         id: doc.id,
       })
 
-      expect(retrievedDoc.value).toEqual('data from rest API')
+      expect(retrievedDoc.value).toEqual('data from REST API')
     })
   })
 
@@ -426,15 +426,19 @@ describe('Hooks', () => {
       expect(JSON.parse(doc.collection_beforeOperation_collection)).toStrictEqual(
         sanitizedHooksCollection,
       )
+
       expect(JSON.parse(doc.collection_beforeChange_collection)).toStrictEqual(
         sanitizedHooksCollection,
       )
+
       expect(JSON.parse(doc.collection_afterChange_collection)).toStrictEqual(
         sanitizedHooksCollection,
       )
+
       expect(JSON.parse(doc.collection_afterRead_collection)).toStrictEqual(
         sanitizedHooksCollection,
       )
+
       expect(JSON.parse(doc.collection_afterOperation_collection)).toStrictEqual(
         sanitizedHooksCollection,
       )