chore!: make optional params required and deprecate outgoing APIs

[paulpopus]

Summary

Resolves all @todo ... in 4.0 markers across packages/payload, packages/drizzle, and packages/richtext-lexical. No new behaviour is introduced — this is purely the enforcement of contracts that were deferred from 3.x.

richtext-lexical: LinkNode persistent ID

• LinkNode now stores a __id field (auto-generated ObjectID via bson-objectid if none is provided) and always emits it in exportJSON at version 3.
• SerializedLinkNode.id is now a required string (was id?: string). AutoLinkNode uses an empty string as it has no concept of a persistent ID.
• Bug fix: the v2→v3 migration (assign a new ObjectID to nodes that lacked one) previously ran after updateFromJSON, making it a no-op for the returned node. It now runs before construction, so the generated id is actually applied.
• updateFromJSON no longer needs the as string cast on serializedNode.id.

richtext-lexical: v1 link node migration removed

The v1→v2 migration (fields.doc.value object → ID) has been removed from LinkNode.importJSON and AutoLinkNode.importJSON. This was tagged @todo remove in 4.0. See the 3.0→4.0 migration guide for manual remediation steps if your database contains pre-3.x link content.

payload / drizzle: parentIsLocalized made required

parentIsLocalized was optional (with @todo make required in v4.0) across every field hook traversal function, getLocalizedPaths, validateSearchParams, PathToQuery, hasLocalesTable, and validateExistingBlockIsIdentical. It is now a required boolean throughout. All call sites that were using field.localized directly now use Boolean(field.localized) to correctly handle the boolean | undefined type. validateQueryPaths now explicitly passes parentIsLocalized: false at the root.

payload: DatabaseAdapterResult.name made required

name on DatabaseAdapterResult was name?: string with a @todo make required in 4.0. It is now name: string.

payload: returning deprecated on all database adapter arg types

Added @deprecated JSDoc to the returning parameter on all ten database adapter operation arg types (CreateArgs, UpdateOneArgs, UpdateManyArgs, UpsertArgs, DeleteOneArgs, CreateVersionArgs, CreateGlobalVersionArgs, UpdateGlobalVersionArgs, CreateGlobalArgs, UpdateGlobalArgs, UpdateJobsArgs).

payload: JobLog.input made required

JobLog.input was input?: Record<string, any> with a @todo make required in 4.0. The type, the collection field config (required: true), and both write paths (handleTaskError, getRunTaskFunction) are updated. Write paths guard with input ?? {} to handle any in-flight undefined values at runtime.

Breaking Changes

SerializedLinkNode.id is now required

// Before
export type SerializedLinkNode<T> = { fields: LinkFields; id?: string } & ...

// After
export type SerializedLinkNode<T> = { fields: LinkFields; id: string } & ...

Any code constructing a SerializedLinkNode literal (e.g. in tests or custom serializers) must now include id: string. Custom node types that extend LinkNode and override exportJSON must include id.

v1 LinkNode / AutoLinkNode migration removed

Content stored in the Payload 2.x / early 3.x link node format (version 1, fields.doc.value as a full object) is no longer automatically migrated on read. Projects that have run Payload 3.x and edited their content through the admin are not affected. See the 3.0→4.0 migration guide for details on detecting and remediating affected content.

parentIsLocalized is now required

The following internal functions now require parentIsLocalized: boolean to be passed explicitly. This affects custom database adapters or plugins that call these functions directly:

• afterChange/traverseFields, afterRead/traverseFields, beforeChange/traverseFields, beforeValidate/traverseFields
• getLocalizedPaths, validateSearchParams
• drizzle: hasLocalesTable, validateExistingBlockIsIdentical

DatabaseAdapterResult.name is now required

Custom database adapters must provide a name: string on the result object returned from the adapter factory.

JobLog.input is now required

JobLog.input is now Record<string, any> (not optional). Code reading JobLog entries should no longer treat input as possibly undefined.

[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	990.16 KB	✅ No change
packages/payload/meta_index.json	esbuild/index.js	1.41 MB	⚠️ +85 B (+0.0%)
packages/payload/meta_shared.json	esbuild/exports/shared.js	192.60 KB	✅ No change
packages/richtext-lexical/meta_client.json	esbuild/exports/client_optimized/index.js	303.83 KB	✅ -294 B (-0.1%)
packages/ui/meta_client.json	esbuild/exports/client_optimized/index.js	1.24 MB	✅ No change
packages/ui/meta_shared.json	esbuild/exports/shared_optimized/index.js	16.11 KB	✅ No change

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}{ ████████████████████▍ }}}$ 81.9%, 807.52 KB
dist/views/Version	${{\color{Goldenrod}{ █▎ }}}$ 5.2%, 51.50 KB
dist/views/Dashboard	${{\color{Goldenrod}{ ▌ }}}$ 2.2%, 21.38 KB
dist/views/Document	${{\color{Goldenrod}{ ▍ }}}$ 1.7%, 16.66 KB
dist/views/List	${{\color{Goldenrod}{ ▍ }}}$ 1.6%, 15.35 KB
dist/elements/Nav	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 10.86 KB
dist/views/Root	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 9.90 KB
dist/views/Versions	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 6.17 KB
dist/views/API	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 6.13 KB
dist/views/Account	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 6.06 KB
dist/elements/DocumentHeader	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 4.71 KB
dist/views/Login	${{\color{Goldenrod}{ }}}$ 0.4%, 4.40 KB
dist/layouts/Root	${{\color{Goldenrod}{ }}}$ 0.4%, 3.53 KB
dist/views/ForgotPassword	${{\color{Goldenrod}{ }}}$ 0.3%, 3.13 KB
dist/views/CreateFirstUser	${{\color{Goldenrod}{ }}}$ 0.3%, 2.81 KB
dist/templates/Default	${{\color{Goldenrod}{ }}}$ 0.3%, 2.62 KB
dist/views/ResetPassword	${{\color{Goldenrod}{ }}}$ 0.2%, 2.40 KB
dist/views/Logout	${{\color{Goldenrod}{ }}}$ 0.2%, 1.94 KB
dist/views/Verify	${{\color{Goldenrod}{ }}}$ 0.1%, 1.29 KB
dist/views/NotFound	${{\color{Goldenrod}{ }}}$ 0.1%, 1.21 KB
(other)	${{\color{Goldenrod}{ ████▌ }}}$ 18.1%, 177.96 KB

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

Path	Size
../../node_modules	${{\color{Goldenrod}{ █████████████████ }}}$ 68.4%, 959.38 KB
dist/fields/hooks	${{\color{Goldenrod}{ ▊ }}}$ 3.1%, 44.11 KB
dist/collections/operations	${{\color{Goldenrod}{ ▋ }}}$ 2.9%, 40.23 KB
dist/versions/migrations	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 18.50 KB
dist/auth/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 15.63 KB
dist/fields/config	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 13.85 KB
dist/globals/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 13.40 KB
dist/utilities/configToJSONSchema.js	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 13.13 KB
dist/queues/operations	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 12.63 KB
dist/fields/validations.js	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 10.57 KB
dist/collections/config	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 9.53 KB
dist/bin/generateImportMap	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 9.44 KB
dist/config/orderable	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.92 KB
dist/uploads/fetchAPI-multipart	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.80 KB
dist/index.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.77 KB
dist/hierarchy/utils	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 7.65 KB
dist/database/migrations	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 7.54 KB
dist/collections/endpoints	${{\color{Goldenrod}{ }}}$ 0.4%, 6.23 KB
dist/auth/strategies	${{\color{Goldenrod}{ }}}$ 0.4%, 5.50 KB
dist/config/sanitize.js	${{\color{Goldenrod}{ }}}$ 0.4%, 5.39 KB
(other)	${{\color{Goldenrod}{ ███████▉ }}}$ 31.6%, 444.10 KB

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

Path	Size
../../node_modules	${{\color{Goldenrod}{ ███████████████████▉ }}}$ 79.5%, 150.12 KB
dist/fields/validations.js	${{\color{Goldenrod}{ █▍ }}}$ 5.6%, 10.57 KB
dist/config/orderable	${{\color{Goldenrod}{ ▍ }}}$ 1.7%, 3.13 KB
dist/fields/baseFields	${{\color{Goldenrod}{ ▍ }}}$ 1.5%, 2.79 KB
dist/utilities/deepCopyObject.js	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 2.54 KB
dist/auth/cookies.js	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 1.55 KB
dist/utilities/flattenTopLevelFields.js	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 1.42 KB
dist/fields/config	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 1.37 KB
dist/utilities/getVersionsConfig.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 1.04 KB
dist/utilities/flattenAllFields.js	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 943 B
dist/utilities/unflatten.js	${{\color{Goldenrod}{ }}}$ 0.4%, 779 B
dist/utilities/sanitizeUserDataForEmail.js	${{\color{Goldenrod}{ }}}$ 0.4%, 713 B
dist/utilities/getFieldPermissions.js	${{\color{Goldenrod}{ }}}$ 0.3%, 651 B
dist/collections/config	${{\color{Goldenrod}{ }}}$ 0.3%, 570 B
dist/bin/generateImportMap	${{\color{Goldenrod}{ }}}$ 0.3%, 561 B
dist/auth/sessions.js	${{\color{Goldenrod}{ }}}$ 0.3%, 525 B
dist/fields/getFieldPaths.js	${{\color{Goldenrod}{ }}}$ 0.3%, 485 B
dist/utilities/appendDateTimezoneSelectFields.js	${{\color{Goldenrod}{ }}}$ 0.2%, 451 B
dist/utilities/getSafeRedirect.js	${{\color{Goldenrod}{ }}}$ 0.2%, 423 B
dist/utilities/deepMerge.js	${{\color{Goldenrod}{ }}}$ 0.2%, 413 B
(other)	${{\color{Goldenrod}{ █████▏ }}}$ 20.5%, 38.70 KB

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

Path	Size
dist/features/blocks	${{\color{Goldenrod}{ ███ }}}$ 12.4%, 37.36 KB
dist/lexical/ui	${{\color{Goldenrod}{ ██▊ }}}$ 11.4%, 34.16 KB
dist/lexical/plugins	${{\color{Goldenrod}{ ██▋ }}}$ 10.9%, 32.88 KB
dist/features/experimental_table	${{\color{Goldenrod}{ ██▎ }}}$ 9.0%, 27.16 KB
dist/packages/@lexical	${{\color{Goldenrod}{ █▌ }}}$ 6.3%, 18.99 KB
dist/features/link	${{\color{Goldenrod}{ █▌ }}}$ 6.2%, 18.51 KB
dist/features/toolbars	${{\color{Goldenrod}{ █▍ }}}$ 5.5%, 16.58 KB
dist/features/upload	${{\color{Goldenrod}{ █▏ }}}$ 4.7%, 14.09 KB
dist/features/textState	${{\color{Goldenrod}{ ▉ }}}$ 3.7%, 11.08 KB
dist/features/relationship	${{\color{Goldenrod}{ ▊ }}}$ 3.1%, 9.39 KB
dist/lexical/utils	${{\color{Goldenrod}{ ▋ }}}$ 2.9%, 8.79 KB
dist/features/converters	${{\color{Goldenrod}{ ▋ }}}$ 2.8%, 8.36 KB
dist/features/debug	${{\color{Goldenrod}{ ▋ }}}$ 2.5%, 7.40 KB
dist/utilities/fieldsDrawer	${{\color{Goldenrod}{ ▌ }}}$ 2.4%, 7.29 KB
dist/lexical/config	${{\color{Goldenrod}{ ▍ }}}$ 1.7%, 5.08 KB
dist/features/lists	${{\color{Goldenrod}{ ▍ }}}$ 1.7%, 5.00 KB
dist/features/format	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 3.46 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}{ ▏ }}}$ 0.9%, 2.84 KB
(other)	${{\color{Goldenrod}{ █████████████████████▉ }}}$ 87.6%, 263.24 KB

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

Path	Size
../../node_modules	${{\color{Goldenrod}{ ███████████▊ }}}$ 47.1%, 579.79 KB
dist/elements/Hierarchy	${{\color{Goldenrod}{ ▉ }}}$ 3.5%, 43.72 KB
dist/elements/BulkUpload	${{\color{Goldenrod}{ ▌ }}}$ 2.3%, 28.18 KB
dist/elements/Table	${{\color{Goldenrod}{ ▍ }}}$ 1.6%, 19.19 KB
dist/views/HierarchyList	${{\color{Goldenrod}{ ▍ }}}$ 1.5%, 18.79 KB
dist/views/Edit	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 17.38 KB
dist/elements/WhereBuilder	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 17.25 KB
dist/forms/Form	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 15.92 KB
dist/fields/Relationship	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 15.48 KB
dist/fields/Blocks	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 15.12 KB
dist/fields/Upload	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 14.39 KB
dist/elements/QueryPresets	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 10.11 KB
dist/elements/PublishButton	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 9.07 KB
dist/elements/HTMLDiff	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.38 KB
dist/views/List	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.03 KB
dist/fields/Array	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.77 KB
dist/elements/ReactSelect	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.75 KB
dist/elements/LivePreview	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.04 KB
dist/elements/RelationshipTable	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 6.88 KB
dist/elements/Upload	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 6.61 KB
(other)	${{\color{Goldenrod}{ █████████████▏ }}}$ 52.9%, 651.92 KB

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

Path	Size
dist/graphics/Logo	${{\color{Goldenrod}{ █████ }}}$ 20.2%, 3.12 KB
../../node_modules	${{\color{Goldenrod}{ ████▎ }}}$ 17.1%, 2.65 KB
dist/graphics/Icon	${{\color{Goldenrod}{ ██▍ }}}$ 9.8%, 1.52 KB
dist/utilities/formatDocTitle	${{\color{Goldenrod}{ ██▏ }}}$ 8.6%, 1.32 KB
dist/providers/TableColumns	${{\color{Goldenrod}{ █▍ }}}$ 5.6%, 866 B
dist/utilities/getGlobalData.js	${{\color{Goldenrod}{ █▏ }}}$ 4.9%, 762 B
dist/utilities/api.js	${{\color{Goldenrod}{ █▏ }}}$ 4.9%, 756 B
dist/utilities/groupNavItems.js	${{\color{Goldenrod}{ █▏ }}}$ 4.7%, 734 B
dist/elements/Translation	${{\color{Goldenrod}{ ▊ }}}$ 3.2%, 493 B
dist/utilities/handleTakeOver.js	${{\color{Goldenrod}{ ▋ }}}$ 2.8%, 440 B
dist/utilities/traverseForLocalizedFields.js	${{\color{Goldenrod}{ ▋ }}}$ 2.6%, 399 B
dist/elements/withMergedProps	${{\color{Goldenrod}{ ▌ }}}$ 2.2%, 339 B
dist/utilities/getNavGroups.js	${{\color{Goldenrod}{ ▌ }}}$ 2.2%, 338 B
dist/utilities/getVisibleEntities.js	${{\color{Goldenrod}{ ▌ }}}$ 2.1%, 329 B
dist/elements/WithServerSideProps	${{\color{Goldenrod}{ ▍ }}}$ 1.5%, 232 B
dist/utilities/handleGoBack.js	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 180 B
dist/fields/mergeFieldStyles.js	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 159 B
dist/utilities/handleBackToDashboard.js	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 152 B
dist/forms/Form	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 147 B
dist/utilities/abortAndIgnore.js	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 146 B
(other)	${{\color{Goldenrod}{ ███████████████████▉ }}}$ 79.8%, 12.36 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.