feat: field path builder #14329

AlessioGr · 2025-10-24T00:27:47Z

Building field paths, schemaPaths and indexPaths for fields and their nested children is way too complex. This PR provides a type-safe utility to build out these field paths. Instead of the function having to manage paths/parent paths/parent index paths/<insert 3 other path types here>, that part is encapsulated within the path builder, thus keeping the consuming function simple and type-safe.

Example

const { path, schemaPath } = getPathBuilder()
  .blocks('content')
  .block('heroBlock')
  .index(0)
  .text('title')
  .build()
// Result:
// {
//   path: 'content.0.title',              // numeric index
//   schemaPath: 'content.heroBlock.title' // block slug
// }

Todo

Write proper PR description
Migrate codebase to use getPathBuilder instead of getFieldPaths. Currently, only buildFormState is migrated.

github-actions · 2025-10-24T17:36:43Z

📦 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	755.52 KB	🆕 Added
packages/payload/meta_index.json	esbuild/index.js	1.23 MB	🆕 Added
packages/payload/meta_shared.json	esbuild/exports/shared.js	162.57 KB	🆕 Added
packages/richtext-lexical/meta_client.json	esbuild/exports/client_optimized/index.js	279.33 KB	🆕 Added
packages/ui/meta_client.json	esbuild/exports/client_optimized/index.js	1.15 MB	🆕 Added
packages/ui/meta_shared.json	esbuild/exports/shared_optimized/index.js	14.39 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}{ ████████████████████ }}}$ 80.2%, 601.84 KB
dist/views/Version	${{\color{Goldenrod}{ █▋ }}}$ 6.6%, 49.56 KB
dist/views/Document	${{\color{Goldenrod}{ ▌ }}}$ 2.1%, 15.43 KB
dist/views/List	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 10.46 KB
dist/views/Root	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 8.61 KB
dist/views/API	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 5.98 KB
dist/views/Versions	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 5.96 KB
dist/elements/Nav	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 5.53 KB
dist/views/Account	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 5.32 KB
dist/elements/DocumentHeader	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 4.81 KB
dist/views/Login	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 4.39 KB
dist/views/Dashboard	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 3.69 KB
dist/layouts/Root	${{\color{Goldenrod}{ }}}$ 0.4%, 3.11 KB
dist/views/ForgotPassword	${{\color{Goldenrod}{ }}}$ 0.4%, 3.09 KB
dist/templates/Default	${{\color{Goldenrod}{ }}}$ 0.4%, 2.83 KB
dist/views/CreateFirstUser	${{\color{Goldenrod}{ }}}$ 0.4%, 2.76 KB
dist/views/BrowseByFolder	${{\color{Goldenrod}{ }}}$ 0.3%, 2.60 KB
dist/views/CollectionFolders	${{\color{Goldenrod}{ }}}$ 0.3%, 2.46 KB
dist/views/ResetPassword	${{\color{Goldenrod}{ }}}$ 0.3%, 2.41 KB
dist/views/Logout	${{\color{Goldenrod}{ }}}$ 0.3%, 1.91 KB
(other)	${{\color{Goldenrod}{ ████▉ }}}$ 19.8%, 149.00 KB

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

Path	Size
../../node_modules	${{\color{Goldenrod}{ █████████████████▎ }}}$ 69.0%, 841.07 KB
dist/fields/hooks	${{\color{Goldenrod}{ ▊ }}}$ 3.4%, 41.94 KB
dist/collections/operations	${{\color{Goldenrod}{ ▊ }}}$ 3.0%, 37.03 KB
dist/auth/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 15.26 KB
dist/queues/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 12.04 KB
dist/globals/operations	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 11.91 KB
dist/fields/config	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 11.57 KB
dist/utilities/configToJSONSchema.js	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 11.54 KB
dist/fields/validations.js	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 10.21 KB
dist/bin/generateImportMap	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.31 KB
dist/collections/config	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.88 KB
dist/database/migrations	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.79 KB
dist/uploads/fetchAPI-multipart	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.74 KB
dist/index.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.51 KB
dist/collections/endpoints	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 6.94 KB
dist/config/orderable	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 6.27 KB
dist/auth/strategies	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 5.50 KB
dist/config/sanitize.js	${{\color{Goldenrod}{ }}}$ 0.4%, 5.44 KB
dist/auth/endpoints	${{\color{Goldenrod}{ }}}$ 0.4%, 5.41 KB
dist/utilities/telemetry	${{\color{Goldenrod}{ }}}$ 0.4%, 5.31 KB
(other)	${{\color{Goldenrod}{ ███████▊ }}}$ 31.0%, 378.70 KB

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

Path	Size
../../node_modules	${{\color{Goldenrod}{ ███████████████████▉ }}}$ 79.7%, 126.93 KB
dist/fields/validations.js	${{\color{Goldenrod}{ █▌ }}}$ 6.4%, 10.21 KB
dist/fields/baseFields	${{\color{Goldenrod}{ ▍ }}}$ 1.8%, 2.79 KB
dist/utilities/deepCopyObject.js	${{\color{Goldenrod}{ ▍ }}}$ 1.6%, 2.48 KB
dist/auth/cookies.js	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 1.55 KB
dist/utilities/flattenTopLevelFields.js	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 1.42 KB
dist/fields/config	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 1.28 KB
dist/utilities/flattenAllFields.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 943 B
dist/folders/utils	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 916 B
dist/utilities/unflatten.js	${{\color{Goldenrod}{ ▏ }}}$ 0.5%, 779 B
dist/utilities/sanitizeUserDataForEmail.js	${{\color{Goldenrod}{ }}}$ 0.4%, 713 B
dist/utilities/getFieldPermissions.js	${{\color{Goldenrod}{ }}}$ 0.4%, 651 B
dist/collections/config	${{\color{Goldenrod}{ }}}$ 0.4%, 570 B
dist/bin/generateImportMap	${{\color{Goldenrod}{ }}}$ 0.4%, 561 B
dist/auth/sessions.js	${{\color{Goldenrod}{ }}}$ 0.3%, 525 B
dist/utilities/getSafeRedirect.js	${{\color{Goldenrod}{ }}}$ 0.3%, 423 B
dist/utilities/deepMerge.js	${{\color{Goldenrod}{ }}}$ 0.3%, 413 B
dist/utilities/formatLabels.js	${{\color{Goldenrod}{ }}}$ 0.2%, 380 B
dist/utilities/appendUploadSelectFields.js	${{\color{Goldenrod}{ }}}$ 0.2%, 360 B
dist/utilities/transformColumnPreferences.js	${{\color{Goldenrod}{ }}}$ 0.2%, 348 B
(other)	${{\color{Goldenrod}{ █████ }}}$ 20.3%, 32.35 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.6%, 34.77 KB
dist/lexical/plugins	${{\color{Goldenrod}{ ██▉ }}}$ 11.5%, 31.68 KB
dist/lexical/ui	${{\color{Goldenrod}{ ██▏ }}}$ 8.8%, 24.36 KB
dist/features/experimental_table	${{\color{Goldenrod}{ ██▏ }}}$ 8.6%, 23.70 KB
dist/packages/@lexical	${{\color{Goldenrod}{ █▋ }}}$ 6.9%, 18.99 KB
dist/features/link	${{\color{Goldenrod}{ █▋ }}}$ 6.5%, 18.04 KB
dist/features/toolbars	${{\color{Goldenrod}{ █▌ }}}$ 6.4%, 17.75 KB
dist/features/upload	${{\color{Goldenrod}{ █▎ }}}$ 5.0%, 13.69 KB
dist/features/textState	${{\color{Goldenrod}{ █ }}}$ 4.0%, 11.08 KB
dist/features/relationship	${{\color{Goldenrod}{ ▊ }}}$ 3.2%, 8.96 KB
dist/lexical/utils	${{\color{Goldenrod}{ ▋ }}}$ 2.9%, 8.08 KB
dist/features/debug	${{\color{Goldenrod}{ ▋ }}}$ 2.7%, 7.39 KB
dist/utilities/fieldsDrawer	${{\color{Goldenrod}{ ▋ }}}$ 2.6%, 7.12 KB
dist/features/converters	${{\color{Goldenrod}{ ▋ }}}$ 2.5%, 7.04 KB
dist/lexical/config	${{\color{Goldenrod}{ ▍ }}}$ 1.8%, 5.08 KB
dist/features/lists	${{\color{Goldenrod}{ ▍ }}}$ 1.8%, 5.00 KB
dist/features/format	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 3.46 KB
dist/lexical/LexicalEditor.js	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 3.17 KB
dist/lexical/theme	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 2.62 KB
dist/features/indent	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 2.50 KB
(other)	${{\color{Goldenrod}{ █████████████████████▊ }}}$ 87.4%, 241.39 KB

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

Path	Size
../../node_modules	${{\color{Goldenrod}{ ████████████▌ }}}$ 50.3%, 572.86 KB
dist/elements/FolderView	${{\color{Goldenrod}{ ▋ }}}$ 2.6%, 29.17 KB
dist/elements/BulkUpload	${{\color{Goldenrod}{ ▌ }}}$ 2.4%, 26.93 KB
dist/elements/WhereBuilder	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 16.25 KB
dist/views/Edit	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 16.04 KB
dist/fields/Relationship	${{\color{Goldenrod}{ ▎ }}}$ 1.4%, 15.40 KB
dist/elements/Table	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 15.29 KB
dist/forms/Form	${{\color{Goldenrod}{ ▎ }}}$ 1.3%, 15.12 KB
dist/fields/Blocks	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 12.87 KB
dist/fields/Upload	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 11.49 KB
dist/elements/PublishButton	${{\color{Goldenrod}{ ▏ }}}$ 0.8%, 8.74 KB
dist/providers/Folders	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.48 KB
dist/elements/LivePreview	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.38 KB
dist/elements/QueryPresets	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 8.36 KB
dist/elements/ListHeader	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 7.83 KB
dist/elements/HTMLDiff	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 7.81 KB
dist/fields/Array	${{\color{Goldenrod}{ ▏ }}}$ 0.7%, 7.56 KB
dist/views/CollectionFolder	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 7.36 KB
dist/views/List	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 6.96 KB
dist/elements/ReactSelect	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 6.91 KB
(other)	${{\color{Goldenrod}{ ████████████▍ }}}$ 49.7%, 566.09 KB

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

Path	Size
dist/graphics/Logo	${{\color{Goldenrod}{ █████▋ }}}$ 22.6%, 3.12 KB
../../node_modules	${{\color{Goldenrod}{ ████▊ }}}$ 19.2%, 2.65 KB
dist/graphics/Icon	${{\color{Goldenrod}{ ██▊ }}}$ 11.0%, 1.52 KB
dist/utilities/formatDocTitle	${{\color{Goldenrod}{ ██▍ }}}$ 9.6%, 1.32 KB
dist/providers/TableColumns	${{\color{Goldenrod}{ █▌ }}}$ 6.2%, 862 B
dist/utilities/groupNavItems.js	${{\color{Goldenrod}{ █▍ }}}$ 5.9%, 814 B
dist/utilities/api.js	${{\color{Goldenrod}{ █▍ }}}$ 5.5%, 756 B
dist/elements/Translation	${{\color{Goldenrod}{ ▉ }}}$ 3.6%, 493 B
dist/utilities/handleTakeOver.js	${{\color{Goldenrod}{ ▊ }}}$ 3.2%, 440 B
dist/elements/withMergedProps	${{\color{Goldenrod}{ ▋ }}}$ 2.5%, 339 B
dist/elements/WithServerSideProps	${{\color{Goldenrod}{ ▍ }}}$ 1.7%, 232 B
dist/utilities/handleGoBack.js	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 168 B
dist/fields/mergeFieldStyles.js	${{\color{Goldenrod}{ ▎ }}}$ 1.2%, 159 B
dist/forms/Form	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 147 B
dist/utilities/abortAndIgnore.js	${{\color{Goldenrod}{ ▎ }}}$ 1.1%, 146 B
dist/utilities/hasSavePermission.js	${{\color{Goldenrod}{ ▎ }}}$ 1.0%, 136 B
dist/utilities/handleBackToDashboard.js	${{\color{Goldenrod}{ ▏ }}}$ 0.9%, 129 B
dist/utilities/findLocaleFromCode.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 84 B
dist/utilities/sanitizeID.js	${{\color{Goldenrod}{ ▏ }}}$ 0.6%, 77 B
dist/utilities/isEditing.js	${{\color{Goldenrod}{ }}}$ 0.4%, 59 B
(other)	${{\color{Goldenrod}{ ███████████████████▎ }}}$ 77.4%, 10.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.

AlessioGr added 11 commits October 23, 2025 13:50

test

86284b8

include schema indexes at the end of path

3ece228

feat: immutability

95c0c4a

feat: Field method

c9643ca

feat: add narrowBuilder helper

ae6a414

chore: add tests to ensure correct result for uncontinued unnamed fields

5ebad39

feat: return indexPath

6ff49e8

prefix

ba95af0

migrate buildformstate

01b900d

chore: simplify types

4315d36

chore: simplify readme

b2273ad

github-actions bot added the created-by: Payload team label Oct 24, 2025

AlessioGr added 3 commits October 24, 2025 10:24

feat: legacySchemaPaths option

837263e

chore: rename FieldAccessors to FieldBuilder

8e9cd86

chore: fix types

582e35e

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: field path builder #14329

feat: field path builder #14329

Uh oh!

AlessioGr commented Oct 24, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Oct 24, 2025

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

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

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

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

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

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

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat: field path builder #14329

Are you sure you want to change the base?

feat: field path builder #14329

Uh oh!

Conversation

AlessioGr commented Oct 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Example

Todo

Uh oh!

github-actions bot commented Oct 24, 2025

📦 esbuild Bundle Analysis for payload

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

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

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

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

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

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

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

AlessioGr commented Oct 24, 2025 •

edited

Loading