tabshift/payloadcms
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

feat: global beforeOperation hook (#13768)

Browse Source 
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
This commit is contained in:
Jacob Fletcher
2025-09-10 16:46:49 -04:00
committed by GitHub
parent 4482eaf9ad
commit 3af546eeee
11 changed files with 143 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/hooks/collections.mdx
View File

@@ -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'
@@ -84,8 +82,8 @@ 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. |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`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. |

26
docs/hooks/globals.mdx
View File

@@ -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.

4
packages/payload/src/collections/config/types.ts
View File

@@ -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
/**

9
packages/payload/src/globals/config/sanitize.ts
View File

@@ -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 = []
}

17
packages/payload/src/globals/config/types.ts
View File

@@ -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[]
}

17
packages/payload/src/globals/operations/countGlobalVersions.ts
View File

@@ -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
// /////////////////////////////////////

17
packages/payload/src/globals/operations/findOne.ts
View File

@@ -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
// /////////////////////////////////////

17
packages/payload/src/globals/operations/restoreVersion.ts
View File

@@ -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
// /////////////////////////////////////

17
packages/payload/src/globals/operations/update.ts
View File

@@ -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)

1
packages/payload/src/index.ts
View File

@@ -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,

22
test/hooks/int.spec.ts
View File

@@ -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,
)