chore: extract sanitizeField from sanitizeFields (#16133)

Extracts per-field sanitization logic into a standalone `sanitizeField`
function that can be called independently. The `sanitizeFields` function
now delegates to `sanitizeField` in a loop, maintaining identical
behavior while exposing the core logic.

This enables sanitizing individual fields after initial config
sanitization, which is needed for the orderable optimization in the
follow-up PR.

Exports `sanitizeField` and `SanitizeFieldArgs` from the payload
package.

Author: JarrodMFlesch

packages/payload/src/collections/config/sanitize.ts

@@ -1,4 +1,5 @@
 import type { Config, SanitizedConfig } from '../../config/types.js'
+import type { OrderableJoinInfo } from '../../fields/config/sanitizeJoinField.js'
 import type {
   CollectionConfig,
   SanitizedCollectionConfig,
@@ -38,6 +39,10 @@ export const sanitizeCollection = async (
    */
   richTextSanitizationPromises?: Array<(config: SanitizedConfig) => Promise<void>>,
   _validRelationships?: string[],
+  /**
+   * Tracker for orderable join fields - populated during sanitization
+   */
+  orderableJoins?: OrderableJoinInfo[],
 ): Promise<SanitizedCollectionConfig> => {
   if (collection._sanitized) {
     return collection as SanitizedCollectionConfig
@@ -67,6 +72,7 @@ export const sanitizeCollection = async (
     fields: sanitized.fields,
     joinPath: '',
     joins,
+    orderableJoins,
     parentIsLocalized: false,
     polymorphicJoins,
     richTextSanitizationPromises,

packages/payload/src/config/orderable/index.ts

@@ -1,98 +1,31 @@
 import { status as httpStatus } from 'http-status'
 
 import type { BeforeChangeHook, CollectionConfig } from '../../collections/config/types.js'
-import type { Field } from '../../fields/config/types.js'
+import type { Config } from '../../config/types.js'
+import type { Field, TextField } from '../../fields/config/types.js'
 import type { Endpoint, PayloadHandler, SanitizedConfig } from '../types.js'
 
 import { executeAccess } from '../../auth/executeAccess.js'
 import { APIError } from '../../errors/index.js'
+import { sanitizeField } from '../../fields/config/sanitize.js'
 import { combineWhereConstraints } from '../../utilities/combineWhereConstraints.js'
 import { commitTransaction } from '../../utilities/commitTransaction.js'
 import { initTransaction } from '../../utilities/initTransaction.js'
 import { killTransaction } from '../../utilities/killTransaction.js'
-import { traverseFields } from '../../utilities/traverseFields.js'
 import { generateKeyBetween, generateNKeysBetween } from './fractional-indexing.js'
 import { getJoinScopeContext } from './utils/getJoinScopeContext.js'
 import { getJoinScopeWhereFromDocData } from './utils/getJoinScopeWhereFromDocData.js'
 import { resolvePendingTargetKey } from './utils/resolvePendingTargetKey.js'
 
-/**
- * This function creates:
- * - N fields per collection, named `_order` or `_<collection>_<joinField>_order`
- * - 1 hook per collection
- * - 1 endpoint per app
- *
- * Also, if collection.defaultSort or joinField.defaultSort is not set, it will be set to the orderable field.
- */
-export const setupOrderable = (config: SanitizedConfig) => {
-  const fieldsToAdd = new Map<CollectionConfig, string[]>()
-  const joinFieldPathsByCollection = new Map<string, Map<string, string>>()
-
-  config.collections.forEach((collection) => {
-    if (collection.orderable) {
-      const currentFields = fieldsToAdd.get(collection) || []
-      fieldsToAdd.set(collection, [...currentFields, '_order'])
-      collection.defaultSort = collection.defaultSort ?? '_order'
-    }
-
-    traverseFields({
-      callback: ({ field, parentRef, ref }) => {
-        if (field.type === 'array' || field.type === 'blocks') {
-          return false
-        }
-        if (field.type === 'group' || field.type === 'tab') {
-          // @ts-expect-error ref is untyped
-          const parentPrefix = parentRef?.prefix ? `${parentRef.prefix}_` : ''
-          // @ts-expect-error ref is untyped
-          ref.prefix = `${parentPrefix}${field.name}`
-        }
-        if (field.type === 'join' && field.orderable === true) {
-          if (Array.isArray(field.collection)) {
-            throw new APIError(
-              'Orderable joins must target a single collection',
-              httpStatus.BAD_REQUEST,
-              {},
-              true,
-            )
-          }
-          const relationshipCollection = config.collections.find((c) => c.slug === field.collection)
-          if (!relationshipCollection) {
-            return false
-          }
-          field.defaultSort = field.defaultSort ?? `_${field.collection}_${field.name}_order`
-          const currentFields = fieldsToAdd.get(relationshipCollection) || []
-          // @ts-expect-error ref is untyped
-          const prefix = parentRef?.prefix ? `${parentRef.prefix}_` : ''
-          const joinOrderableFieldName = `_${field.collection}_${prefix}${field.name}_order`
-          fieldsToAdd.set(relationshipCollection, [...currentFields, joinOrderableFieldName])
-
-          const currentJoinFieldPaths =
-            joinFieldPathsByCollection.get(relationshipCollection.slug) || new Map<string, string>()
-          currentJoinFieldPaths.set(joinOrderableFieldName, field.on)
-          joinFieldPathsByCollection.set(relationshipCollection.slug, currentJoinFieldPaths)
-        }
-      },
-      fields: collection.fields,
-    })
-  })
-
-  Array.from(fieldsToAdd.entries()).forEach(([collection, orderableFields]) => {
-    addOrderableFieldsAndHook(collection, orderableFields, joinFieldPathsByCollection)
-  })
-
-  if (fieldsToAdd.size > 0) {
-    addOrderableEndpoint(config, joinFieldPathsByCollection)
-  }
-}
-
-export const addOrderableFieldsAndHook = (
+export const addOrderableFieldsAndHook = async (
   collection: CollectionConfig,
+  config: Config,
   orderableFieldNames: string[],
   joinFieldPathsByCollection?: Map<string, Map<string, string>>,
 ) => {
-  // 1. Add field
-  orderableFieldNames.forEach((orderableFieldName) => {
-    const orderField: Field = {
+  // 1. Add fields
+  for (const orderableFieldName of orderableFieldNames) {
+    const orderField: TextField = {
       name: orderableFieldName,
       type: 'text',
       admin: {
@@ -114,8 +47,24 @@ export const addOrderableFieldsAndHook = (
       index: true,
     }
 
+    // Sanitize the field using the standard sanitization logic
+    await sanitizeField({
+      collectionConfig: collection,
+      config,
+      existingFieldNames: new Set(),
+      field: orderField,
+      index: 0,
+      isTopLevelField: true,
+      joinPath: '',
+      parentIndexPath: '',
+      parentIsLocalized: false,
+      parentSchemaPath: '',
+      requireFieldLevelRichTextEditor: false,
+      validRelationships: null,
+    })
+
     collection.fields.unshift(orderField)
-  })
+  }
 
   // 2. Add hook
   if (!collection.hooks) {

packages/payload/src/config/sanitize.ts

@@ -3,6 +3,7 @@ import type { AcceptedLanguages } from '@payloadcms/translations'
 import { en } from '@payloadcms/translations/languages/en'
 import { deepMergeSimple } from '@payloadcms/translations/utilities'
 
+import type { OrderableJoinInfo } from '../fields/config/sanitizeJoinField.js'
 import type { CollectionSlug, GlobalSlug, SanitizedCollectionConfig } from '../index.js'
 import type { SanitizedJobsConfig } from '../queues/config/types/index.js'
 import type {
@@ -33,12 +34,12 @@ import { getPreferencesCollection, preferencesCollectionSlug } from '../preferen
 import { getQueryPresetsConfig, queryPresetsCollectionSlug } from '../query-presets/config.js'
 import { getDefaultJobsCollection, jobsCollectionSlug } from '../queues/config/collection.js'
 import { getJobStatsGlobal } from '../queues/config/global.js'
-import { flattenBlock } from '../utilities/flattenAllFields.js'
+import { flattenAllFields, flattenBlock } from '../utilities/flattenAllFields.js'
 import { hasScheduledPublishEnabled } from '../utilities/getVersionsConfig.js'
 import { validateTimezones } from '../utilities/validateTimezones.js'
 import { getSchedulePublishTask } from '../versions/schedule/job.js'
 import { addDefaultsToConfig } from './defaults.js'
-import { setupOrderable } from './orderable/index.js'
+import { addOrderableEndpoint, addOrderableFieldsAndHook } from './orderable/index.js'
 
 const sanitizeAdminConfig = (configToSanitize: Config): Partial<SanitizedConfig> => {
   const sanitizedConfig = { ...configToSanitize }
@@ -118,9 +119,6 @@ export const sanitizeConfig = async (incomingConfig: Config): Promise<SanitizedC
 
   const config: Partial<SanitizedConfig> = sanitizeAdminConfig(configWithDefaults)
 
-  // Add orderable fields
-  setupOrderable(config as SanitizedConfig)
-
   if (!config.endpoints) {
     config.endpoints = []
   }
@@ -261,6 +259,9 @@ export const sanitizeConfig = async (incomingConfig: Config): Promise<SanitizedC
 
   const folderEnabledCollections: SanitizedCollectionConfig[] = []
 
+  // Track orderable join fields during sanitization
+  const orderableJoins: OrderableJoinInfo[] = []
+
   for (let i = 0; i < config.collections!.length; i++) {
     if (collectionSlugs.has(config.collections![i]!.slug)) {
       throw new DuplicateCollection('slug', config.collections![i]!.slug)
@@ -296,13 +297,60 @@ export const sanitizeConfig = async (incomingConfig: Config): Promise<SanitizedC
       config.collections![i]!,
       richTextSanitizationPromises,
       validRelationships,
+      orderableJoins,
     )
 
     if (config.folders !== false && config.collections![i]!.folders) {
       folderEnabledCollections.push(config.collections![i]!)
     }
   }
 
+  // Process orderable features after all collections are sanitized
+  const fieldsToAdd = new Map<SanitizedCollectionConfig, string[]>()
+  const joinFieldPathsByCollection = new Map<string, Map<string, string>>()
+
+  // Handle collection.orderable
+  for (const collection of config.collections!) {
+    if (collection.orderable) {
+      const currentFields = fieldsToAdd.get(collection) || []
+      fieldsToAdd.set(collection, [...currentFields, '_order'])
+      collection.defaultSort = collection.defaultSort ?? '_order'
+    }
+  }
+
+  // Handle orderable join fields (tracked during sanitization)
+  for (const joinInfo of orderableJoins) {
+    const targetCollection = config.collections!.find(
+      (c) => c.slug === joinInfo.targetCollectionSlug,
+    )
+    if (targetCollection) {
+      const currentFields = fieldsToAdd.get(targetCollection) || []
+      fieldsToAdd.set(targetCollection, [...currentFields, joinInfo.orderFieldName])
+
+      const currentJoinFieldPaths =
+        joinFieldPathsByCollection.get(targetCollection.slug) || new Map<string, string>()
+      currentJoinFieldPaths.set(joinInfo.orderFieldName, joinInfo.joinFieldOn)
+      joinFieldPathsByCollection.set(targetCollection.slug, currentJoinFieldPaths)
+    }
+  }
+
+  // Add fields, hooks, and update flattenedFields
+  for (const [collection, orderableFields] of fieldsToAdd) {
+    await addOrderableFieldsAndHook(
+      collection,
+      config as unknown as Config,
+      orderableFields,
+      joinFieldPathsByCollection,
+    )
+    // Regenerate flattenedFields since we added new fields
+    collection.flattenedFields = flattenAllFields({ fields: collection.fields })
+  }
+
+  // Add endpoint if any orderable features exist
+  if (fieldsToAdd.size > 0) {
+    addOrderableEndpoint(config as SanitizedConfig, joinFieldPathsByCollection)
+  }
+
   if (config.globals!.length > 0) {
     for (let i = 0; i < config.globals!.length; i++) {
       if (hasScheduledPublishEnabled(config.globals![i]!)) {