refactor(payload): pass literal operation to buildBeforeOperation

[DanRibbens]

What / Why

Resolves the buildBeforeOperation.ts TODO to "remove overloads and operations should be the literal operation that was called" — the non-controversial slice of the v4 beforeOperation cleanup.

The find, findByID, findDistinct, deleteByID, and updateByID operations now pass their literal operation name to buildBeforeOperation instead of coarse aliases ('read', 'readDistinct', 'delete', 'update'). With every caller now passing a literal op, the six deprecated per-operation overloads collapse into a single generic passthrough overload.

Behavior is unchanged

operationToHookOperation still maps the internal op to the public hook operation, so user beforeOperation hooks continue to receive 'read', 'readDistinct', 'delete', and 'update' — matching the promise in docs/migration-guide/v4.mdx ("The operation: 'read' value on the beforeOperation hook is unchanged.") and the existing integration tests.

Deferred follow-up

The remaining TODOs change what value beforeOperation hooks receive (a breaking change) and are tracked, with a full checklist, in PYLD-2687.

Verification

• pnpm build:types (payload tsc): 0 errors
• pnpm test:int hooks -t beforeOperation: 13 passed (hook still receives 'read'/'readDistinct'/'delete'/'update')
• ESLint on changed files: clean

🤖 Generated with Claude Code

[github-actions]

Pull Request titles must follow the Conventional Commits specification and have valid scopes.

Unknown scope "payload" found in pull request title "refactor(payload): pass literal operation to buildBeforeOperation". Scope must match one of: cpa, claude, codemod, db-*, db-d1-sqlite, db-mongodb, db-postgres, db-vercel-postgres, db-sqlite, db-d1-sqlite, drizzle, email-*, email-nodemailer, email-resend, eslint, evals, graphql, kv, kv-redis, live-preview, live-preview-react, live-preview-vue, next, payload-cloud, plugin-cloud, plugin-cloud-storage, plugin-ecommerce, plugin-form-builder, plugin-import-export, plugin-mcp, plugin-multi-tenant, plugin-nested-docs, plugin-redirects, plugin-search, plugin-sentry, plugin-seo, plugin-stripe, richtext-*, richtext-lexical, sdk, skills, storage-*, storage-azure, storage-gcs, storage-r2, storage-vercel-blob, storage-s3, tanstack-start, translations, ui, templates, examples(/(\w|-)+)?, deps.

feat(ui): add Button component
^    ^    ^
|    |    |__ Subject
|    |_______ Scope
|____________ Type

[github-actions]

📦 esbuild Bundle Analysis for payload

This analysis was generated by esbuild-bundle-analyzer. 🤖

Meta File	Out File	Size (raw)	Note
packages/next/meta_index.json	esbuild/index.js	213.92 KB	🆕 Added
packages/payload/meta_index.json	esbuild/index.js	1.40 MB	🆕 Added
packages/payload/meta_shared.json	esbuild/exports/shared.js	213.39 KB	🆕 Added
packages/richtext-lexical/meta_client.json	esbuild/exports/client_optimized/index.js	286.50 KB	🆕 Added
packages/ui/meta_client.json	esbuild/exports/client_optimized/index.js	36.54 KB	🆕 Added
packages/ui/meta_shared.json	esbuild/exports/shared_optimized/index.js	18.95 KB	🆕 Added

Largest paths

These visualization shows top 20 largest paths in the bundle.

Meta file: packages/next/meta_index.json, Out file: esbuild/index.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ ████████████████████████▊ }}}$ 99.0%, 209.89 KB
dist/adapters/router.js	${{\color{Goldenrod}{ }}}$ 0.3%, 718 B
dist/adapters/server.js	${{\color{Goldenrod}{ }}}$ 0.3%, 533 B
dist/adapters/layout.js	${{\color{Goldenrod}{ }}}$ 0.2%, 526 B
dist/adapters/views.js	${{\color{Goldenrod}{ }}}$ 0.2%, 409 B
dist/esbuildEntry.js	${{\color{Goldenrod}{ }}}$ 0.0%, 0 B

Meta file: packages/payload/meta_index.json, Out file: esbuild/index.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ ████████████████▉ }}}$ 67.6%, 944.37 KB
dist/fields/hooks	${{\color{Goldenrod}{ ▊ }}}$ 3.2%, 44.38 KB
dist/collections/operations	${{\color{Goldenrod}{ ▊ }}}$ 3.1%, 43.25 KB
dist/utilities/configToJSONSchema.js	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 15.99 KB
dist/auth/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 15.63 KB
dist/queues/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 14.29 KB
dist/fields/config	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 13.63 KB
dist/globals/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 13.53 KB
dist/fields/validations.js	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 10.69 KB
dist/collections/config	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 9.93 KB
dist/bin/generateImportMap	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 9.84 KB
dist/config/orderable	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 8.07 KB
dist/uploads/fetchAPI-multipart	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.87 KB
dist/index.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.78 KB
dist/hierarchy/utils	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 7.64 KB
dist/database/migrations	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 7.55 KB
dist/config/sanitize.js	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 7.07 KB
dist/collections/endpoints	${{\color{Goldenrod}{ }}}$ 0.4%, 6.12 KB
dist/auth/strategies	${{\color{Goldenrod}{ }}}$ 0.4%, 5.61 KB
dist/uploads/endpoints	${{\color{Goldenrod}{ }}}$ 0.4%, 5.58 KB
(other)	${{\color{Goldenrod}{ ████████ }}}$ 32.4%, 451.90 KB

Meta file: packages/payload/meta_shared.json, Out file: esbuild/exports/shared.js

Path	Size
../../node_modules	${{\color{Goldenrod}{ █████████████████▉ }}}$ 71.9%, 150.13 KB
dist/fields/validations.js	${{\color{Goldenrod}{ █▎ }}}$ 5.1%, 10.69 KB
dist/fields/config	${{\color{Goldenrod}{ ▋ }}}$ 2.8%, 5.83 KB
dist/utilities/traverseFields.js	${{\color{Goldenrod}{ ▌ }}}$ 2.1%, 4.45 KB
dist/collections/config	${{\color{Goldenrod}{ ▍ }}}$ 1.6%, 3.33 KB
dist/config/orderable	${{\color{Goldenrod}{ ▍ }}}$ 1.5%, 3.13 KB
dist/fields/baseFields	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 2.79 KB
dist/utilities/deepCopyObject.js	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 2.69 KB
dist/config/client.js	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 2.69 KB
dist/auth/cookies.js	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 1.55 KB
dist/utilities/flattenTopLevelFields.js	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 1.41 KB
dist/utilities/getVersionsConfig.js	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 1.04 KB
dist/globals/config	${{\color{Goldenrod}{ }}}$ 0.4%, 939 B
dist/utilities/flattenAllFields.js	${{\color{Goldenrod}{ }}}$ 0.4%, 793 B
dist/utilities/unflatten.js	${{\color{Goldenrod}{ }}}$ 0.4%, 779 B
dist/utilities/sanitizeUserDataForEmail.js	${{\color{Goldenrod}{ }}}$ 0.3%, 713 B
dist/auth/extractJWT.js	${{\color{Goldenrod}{ }}}$ 0.3%, 696 B
dist/utilities/getFieldPermissions.js	${{\color{Goldenrod}{ }}}$ 0.3%, 651 B
dist/utilities/getSafeRedirect.js	${{\color{Goldenrod}{ }}}$ 0.3%, 632 B
dist/errors/ValidationError.js	${{\color{Goldenrod}{ }}}$ 0.3%, 577 B
(other)	${{\color{Goldenrod}{ ███████ }}}$ 28.1%, 58.78 KB

Meta file: packages/richtext-lexical/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Path	Size
dist/features/blocks	${{\color{Goldenrod}{ ███▎ }}}$ 13.1%, 37.20 KB
dist/lexical/ui	${{\color{Goldenrod}{ ███ }}}$ 12.1%, 34.20 KB
dist/lexical/plugins	${{\color{Goldenrod}{ ██▉ }}}$ 11.7%, 33.01 KB
dist/features/table	${{\color{Goldenrod}{ ██▍ }}}$ 9.6%, 27.22 KB
dist/features/link	${{\color{Goldenrod}{ █▋ }}}$ 6.6%, 18.82 KB
dist/features/toolbars	${{\color{Goldenrod}{ █▌ }}}$ 6.2%, 17.45 KB
dist/features/upload	${{\color{Goldenrod}{ █▎ }}}$ 5.0%, 14.28 KB
dist/features/textState	${{\color{Goldenrod}{ ▉ }}}$ 3.9%, 11.08 KB
dist/lexical/utils	${{\color{Goldenrod}{ ▉ }}}$ 3.5%, 10.02 KB
dist/features/relationship	${{\color{Goldenrod}{ ▊ }}}$ 3.4%, 9.61 KB
dist/features/converters	${{\color{Goldenrod}{ ▊ }}}$ 3.0%, 8.36 KB
dist/utilities/fieldsDrawer	${{\color{Goldenrod}{ ▋ }}}$ 2.9%, 8.12 KB
dist/features/debug	${{\color{Goldenrod}{ ▋ }}}$ 2.6%, 7.40 KB
dist/lexical/config	${{\color{Goldenrod}{ ▍ }}}$ 1.8%, 5.14 KB
dist/features/lists	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 3.64 KB
dist/features/format	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 3.28 KB
dist/lexical/LexicalEditor.js	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 3.23 KB
dist/features/horizontalRule	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 3.18 KB
dist/field/Field.js	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 2.88 KB
dist/lexical/nodes	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 2.66 KB
(other)	${{\color{Goldenrod}{ █████████████████████▋ }}}$ 86.9%, 246.09 KB

Meta file: packages/ui/meta_client.json, Out file: esbuild/exports/client_optimized/index.js

Path	Size
dist/exports/client	${{\color{Goldenrod}{ █████████████████████████ }}}$ 100.0%, 26.90 KB

Meta file: packages/ui/meta_shared.json, Out file: esbuild/exports/shared_optimized/index.js

Path	Size
dist/graphics/Logo	${{\color{Goldenrod}{ ███████▋ }}}$ 30.5%, 5.57 KB
../../node_modules	${{\color{Goldenrod}{ ███▌ }}}$ 14.5%, 2.65 KB
dist/graphics/Icon	${{\color{Goldenrod}{ ██ }}}$ 8.3%, 1.51 KB
dist/utilities/formatDocTitle	${{\color{Goldenrod}{ █▊ }}}$ 7.2%, 1.32 KB
dist/providers/TableColumns	${{\color{Goldenrod}{ █▏ }}}$ 4.7%, 866 B
dist/utilities/getGlobalData.js	${{\color{Goldenrod}{ █ }}}$ 4.2%, 762 B
dist/utilities/api.js	${{\color{Goldenrod}{ █ }}}$ 4.1%, 756 B
dist/utilities/groupNavItems.js	${{\color{Goldenrod}{ █ }}}$ 4.1%, 745 B
dist/elements/Translation	${{\color{Goldenrod}{ ▋ }}}$ 2.7%, 493 B
dist/utilities/handleTakeOver.js	${{\color{Goldenrod}{ ▌ }}}$ 2.4%, 440 B
dist/utilities/traverseForLocalizedFields.js	${{\color{Goldenrod}{ ▌ }}}$ 2.3%, 419 B
dist/elements/withMergedProps	${{\color{Goldenrod}{ ▍ }}}$ 1.9%, 339 B
dist/utilities/getNavGroups.js	${{\color{Goldenrod}{ ▍ }}}$ 1.9%, 338 B
dist/utilities/getVisibleEntities.js	${{\color{Goldenrod}{ ▍ }}}$ 1.8%, 329 B
dist/elements/WithServerSideProps	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 232 B
dist/layouts/Root	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 230 B
dist/utilities/handleGoBack.js	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 180 B
dist/fields/mergeFieldStyles.js	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 158 B
dist/forms/Form	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 152 B
dist/utilities/handleBackToDashboard.js	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 152 B
(other)	${{\color{Goldenrod}{ █████████████████▍ }}}$ 69.5%, 12.68 KB

Details

Next to the size is how much the size has increased or decreased compared with the base branch of this PR.

• ‼️: Size increased by 20% or more. Special attention should be given to this.
• ⚠️: Size increased in acceptable range (lower than 20%).
• ✅: No change or even downsized.
• 🗑️: The out file is deleted: not found in base branch.
• 🆕: The out file is newly found: will be added to base branch.

[DanRibbens]

The deferred breaking-change follow-up (removing the operationToHookOperation mapping and the 'read'/'readDistinct' union options, plus the migrate-before-operation-read codemod) is tracked with a full checklist in PYLD-2687.