feat: global beforeOperation hook (#13768)

jacobsfletch · web-flow · commit 3af546eeeeac · 2025-09-10T20:46:49.000Z
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
diff --git a/docs/hooks/collections.mdx b/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                                                                                                                                           |
-| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **`collection`** | The [Collection](../configuration/collections) in which this Hook is running against.                                                                 |
-| **`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. |
+| Option           | Description                                                                                                                                                                                                                                                                               |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`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).                                                                                                                                                                                                                           |
+| **`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
 
diff --git a/docs/hooks/globals.mdx b/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.
diff --git a/packages/payload/src/collections/config/types.ts b/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
   /**
diff --git a/packages/payload/src/globals/config/sanitize.ts b/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,35 +34,43 @@ export const sanitizeGlobal = async (
   // /////////////////////////////////
 
   global.endpoints = global.endpoints ?? []
+
   if (!global.hooks) {
     global.hooks = {}
   }
+
   if (!global.access) {
     global.access = {}
   }
+
   if (!global.admin) {
     global.admin = {}
   }
 
   if (!global.access.read) {
     global.access.read = defaultAccess
   }
+
   if (!global.access.update) {
     global.access.update = defaultAccess
   }
 
   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 = []
   }
diff --git a/packages/payload/src/globals/config/types.ts b/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[]
   }
diff --git a/packages/payload/src/globals/operations/countGlobalVersions.ts b/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
     // /////////////////////////////////////
diff --git a/packages/payload/src/globals/operations/findOne.ts b/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
     // /////////////////////////////////////
diff --git a/packages/payload/src/globals/operations/restoreVersion.ts b/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
     // /////////////////////////////////////
diff --git a/packages/payload/src/globals/operations/update.ts b/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)
diff --git a/packages/payload/src/index.ts b/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,
diff --git a/test/hooks/int.spec.ts b/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,
       )

Original file line number	Diff line number	Diff line change
`@@ -24,6 +24,7 @@ export const sanitizeGlobal = async (`
`24`	`24`	`if (global._sanitized) {`
`25`	`25`	`return global as SanitizedGlobalConfig`
`26`	`26`	`}`
	`27`	`+`
`27`	`28`	`global._sanitized = true`
`28`	`29`
`29`	`30`	`global.label = global.label \|\| toWords(global.slug)`
`@@ -33,35 +34,43 @@ export const sanitizeGlobal = async (`
`33`	`34`	`// /////////////////////////////////`
`34`	`35`
`35`	`36`	`global.endpoints = global.endpoints ?? []`
	`37`	`+`
`36`	`38`	`if (!global.hooks) {`
`37`	`39`	`global.hooks = {}`
`38`	`40`	`}`
	`41`	`+`
`39`	`42`	`if (!global.access) {`
`40`	`43`	`global.access = {}`
`41`	`44`	`}`
	`45`	`+`
`42`	`46`	`if (!global.admin) {`
`43`	`47`	`global.admin = {}`
`44`	`48`	`}`
`45`	`49`
`46`	`50`	`if (!global.access.read) {`
`47`	`51`	`global.access.read = defaultAccess`
`48`	`52`	`}`
	`53`	`+`
`49`	`54`	`if (!global.access.update) {`
`50`	`55`	`global.access.update = defaultAccess`
`51`	`56`	`}`
`52`	`57`
`53`	`58`	`if (!global.hooks.beforeValidate) {`
`54`	`59`	`global.hooks.beforeValidate = []`
`55`	`60`	`}`
	`61`	`+`
`56`	`62`	`if (!global.hooks.beforeChange) {`
`57`	`63`	`global.hooks.beforeChange = []`
`58`	`64`	`}`
	`65`	`+`
`59`	`66`	`if (!global.hooks.afterChange) {`
`60`	`67`	`global.hooks.afterChange = []`
`61`	`68`	`}`
	`69`	`+`
`62`	`70`	`if (!global.hooks.beforeRead) {`
`63`	`71`	`global.hooks.beforeRead = []`
`64`	`72`	`}`
	`73`	`+`
`65`	`74`	`if (!global.hooks.afterRead) {`
`66`	`75`	`global.hooks.afterRead = []`
`67`	`76`	`}`