feat(plugin-import-export): out of beta and added support for collection-level and field-level hooks (#16556)

### Plugin out of beta

The import export plugin is now marked as stable and will be moved out
of beta. For v4 we will be removing the deprecated APIs but for v3 they
will remain supported.

### Why

Field-level hooks are essential because:

1. **Co-location** — the transform behavior lives next to the field
definition, not in a separate collection config
2. **Reusability** — a shared field config carries its hooks to every
collection that uses it, zero duplication
3. **Deeply nested fields** — transforming
`group.tabs.namedTab.array[0].field` in a collection-level hook requires
manually navigating the full document structure; field-level hooks
handle this transparently

This PR keeps both levels: field-level hooks for per-field transforms,
collection-level hooks for batch-wide operations (masking, logging,
filtering).


## Field-level hooks

Defined per-field via `custom['plugin-import-export'].hooks`:

```ts
import type { FieldBeforeExportHook } from '@payloadcms/plugin-import-export'

const authorField = {
  name: 'author',
  type: 'relationship',
  relationTo: 'users',
  custom: {
    'plugin-import-export': {
      hooks: {
        // Runs before the field value is written to the export file
        beforeExport: (({ value, columnName, row, format }) => {
          if (format === 'csv' && value && typeof value === 'object' && 'id' in value) {
            row[`${columnName}_id`] = value.id
            row[`${columnName}_email`] = value.email
            return undefined // let row mutation take effect
          }
          return value
        }) satisfies FieldBeforeExportHook,

        // Runs before the field value is written to the database
        beforeImport: ({ value, columnName, data, format }) => {
          if (format === 'csv') {
            return data[`${columnName}_id`] ?? undefined
          }
          return value
        },
      },
    },
  },
}
```

## Collection-level hooks
Defined in the plugin config:

```ts
importExportPlugin({
  collections: [
    {
      slug: 'users',
      export: {
        hooks: {
          before: ({ data, format }) => {
            // Mask sensitive fields from the entire batch
            return data.map(({ passwordHash, ssn, ...safe }) => safe)
          },
          after: ({ batchNumber, totalBatches, req }) => {
            req.payload.logger.info(`Export batch ${batchNumber}/${totalBatches} written`)
          },
        },
      },
    },
  ],
})
```

#### Execution order

field-level `hooks.beforeExport` / `hooks.beforeImport` run first
(per-field, per-document), then collection-level `hooks.before` /
`hooks.after` run on the already-transformed batch.

#### Migration from toCSV / fromCSV

toCSV and fromCSV remain fully functional but are deprecated — removed
in v4.0. Migration is a 1:1 rename plus the new format parameter:


```ts
// Before (deprecated)
custom: {
  'plugin-import-export': {
    toCSV: ({ value, row }) => { ... },
    fromCSV: ({ value, data }) => { ... },
  },
}

// After
custom: {
  'plugin-import-export': {
    hooks: {
      beforeExport: ({ value, row, format }) => { ... },
      beforeImport: ({ value, data, format }) => { ... },
    },
  },
}

```

## What changed

### New types

`FieldBeforeExportHook` — field-level export hook type (same args as
ToCSVFunction + format)
`FieldBeforeImportHook` — field-level import hook type (same args as
FromCSVFunction + format)
`ToCSVFunction` / `FromCSVFunction` — now deprecated aliases

#### JSON format support (new)

- Field-level hooks now fire for JSON exports/imports, not just CSV
- New applyFieldExportHooks / applyFieldImportHooks utilities traverse
nested JSON documents and apply field hooks at each position
- Preview handlers also apply field hooks for both CSV and JSON

## Bug fixes

- [x] Fixed parentPath key computation in getExportFieldFunctions /
getImportFieldFunctions — named tabs inside groups now produce correct
underscore-separated keys (pre-existing bug)
- [x] Fixed slice(-0) bug in import batchProcessor.ts — ImportAfterHook
was receiving all accumulated errors instead of per-batch errors when a
batch had zero failures
- [x] Removed unused fs import from hooks.int.spec.ts

## Renamed internals

- toCSVFunctions → exportFieldHooks throughout all source files
- fromCSVFunctions → importFieldHooks throughout all source files
- Error messages updated from "toCSVFunction" to "field export hook"

## Checklist
- [x] Documentation updated with new API, migration guide, execution
order
- [x]  Test collection PostsWithFieldHooks with field-level hooks
- [x] 12 new integration tests (CSV export, JSON export, format
parameter, deeply nested fields, CSV import, JSON import, backward
compatibility with toCSV, backward compatibility with fromCSV, execution
order, reusable field config, priority, default behaviour)

Author: paulpopus

docs/plugins/import-export.mdx

@@ -4,6 +4,8 @@
  */
 import type { PayloadRequest, SelectType, Sort, TypedUser, Where } from 'payload'
 
+import type { ExportAfterHook, ExportBeforeHook } from '../types.js'
+
 import { type BatchProcessorOptions } from '../utilities/useBatchProcessor.js'
 
 /**
@@ -46,6 +48,11 @@ export interface ExportProcessOptions<TDoc = unknown> {
    * The export format - affects column tracking for CSV
    */
   format: 'csv' | 'json'
+  /** Lifecycle hooks for this export operation */
+  hooks?: {
+    after?: ExportAfterHook
+    before?: ExportBeforeHook
+  }
   /**
    * Maximum number of documents to export
    */
@@ -58,6 +65,8 @@ export interface ExportProcessOptions<TDoc = unknown> {
    * Starting page for pagination (default: 1)
    */
   startPage?: number
+  /** Total number of docs available (used to compute totalBatches for hooks) */
+  totalDocs?: number
   /**
    * Transform function to apply to each document
    */
@@ -98,14 +107,22 @@ export interface ExportResult {
  *   format: 'csv',
  *   maxDocs: 1000,
  *   req,
- *   transformDoc: (doc) => flattenObject({ doc }),
+ *   transformDoc: (doc) => flattenObject({ data: doc }),
  * })
  * ```
  */
 export function createExportBatchProcessor(options: ExportBatchProcessorOptions = {}) {
   const batchSize = options.batchSize ?? 100
   const debug = options.debug ?? false
 
+  const computeTotalBatches = (totalDocs: number | undefined, maxDocs: number): number => {
+    const effectiveDocs =
+      totalDocs !== undefined
+        ? Math.min(totalDocs, maxDocs === Number.POSITIVE_INFINITY ? totalDocs : maxDocs)
+        : 0
+    return effectiveDocs > 0 ? Math.ceil(effectiveDocs / batchSize) : 1
+  }
+
   /**
    * Process an export operation by fetching and transforming documents in batches.
    *
@@ -115,7 +132,18 @@ export function createExportBatchProcessor(options: ExportBatchProcessorOptions
   const processExport = async <TDoc>(
     processOptions: ExportProcessOptions<TDoc>,
   ): Promise<ExportResult> => {
-    const { findArgs, format, maxDocs, req, startPage = 1, transformDoc } = processOptions
+    const {
+      findArgs,
+      format,
+      hooks,
+      maxDocs,
+      req,
+      startPage = 1,
+      totalDocs,
+      transformDoc,
+    } = processOptions
+
+    const totalBatches = computeTotalBatches(totalDocs, maxDocs)
 
     const docs: Record<string, unknown>[] = []
     const columnsSet = new Set<string>()
@@ -144,13 +172,27 @@ export function createExportBatchProcessor(options: ExportBatchProcessorOptions
         )
       }
 
-      for (const doc of result.docs) {
-        const transformedDoc = transformDoc(doc as TDoc)
-        docs.push(transformedDoc)
+      const batchNumber = currentPage - startPage + 1
+      const originalDocs = result.docs as Record<string, unknown>[]
+      const batchData = result.docs.map((doc) => transformDoc(doc as TDoc))
+
+      const dataToWrite =
+        hooks?.before && batchData.length > 0
+          ? await hooks.before({
+              batchNumber,
+              data: batchData,
+              format,
+              originalData: originalDocs,
+              req,
+              totalBatches,
+            })
+          : batchData
+
+      for (const row of dataToWrite) {
+        docs.push(row)
 
-        // Track columns for CSV format
         if (format === 'csv') {
-          for (const key of Object.keys(transformedDoc)) {
+          for (const key of Object.keys(row)) {
             if (!columnsSet.has(key)) {
               columnsSet.add(key)
               columns.push(key)
@@ -159,6 +201,17 @@ export function createExportBatchProcessor(options: ExportBatchProcessorOptions
         }
       }
 
+      if (hooks?.after && dataToWrite.length > 0) {
+        await hooks.after({
+          batchNumber,
+          data: dataToWrite,
+          format,
+          originalData: originalDocs,
+          req,
+          totalBatches,
+        })
+      }
+
       fetched += result.docs.length
       hasNextPage = result.hasNextPage && fetched < maxDocs
       currentPage++
@@ -187,7 +240,18 @@ export function createExportBatchProcessor(options: ExportBatchProcessorOptions
   async function* streamExport<TDoc>(
     processOptions: ExportProcessOptions<TDoc>,
   ): AsyncGenerator<{ columns: string[]; docs: Record<string, unknown>[] }> {
-    const { findArgs, format, maxDocs, req, startPage = 1, transformDoc } = processOptions
+    const {
+      findArgs,
+      format,
+      hooks,
+      maxDocs,
+      req,
+      startPage = 1,
+      totalDocs,
+      transformDoc,
+    } = processOptions
+
+    const totalBatches = computeTotalBatches(totalDocs, maxDocs)
 
     const columnsSet = new Set<string>()
     const columns: string[] = []
@@ -215,15 +279,25 @@ export function createExportBatchProcessor(options: ExportBatchProcessorOptions
         )
       }
 
-      const batchDocs: Record<string, unknown>[] = []
-
-      for (const doc of result.docs) {
-        const transformedDoc = transformDoc(doc as TDoc)
-        batchDocs.push(transformedDoc)
-
-        // Track columns for CSV format
+      const batchNumber = currentPage - startPage + 1
+      const originalDocs = result.docs as Record<string, unknown>[]
+      const batchData = result.docs.map((doc) => transformDoc(doc as TDoc))
+
+      const dataToWrite =
+        hooks?.before && batchData.length > 0
+          ? await hooks.before({
+              batchNumber,
+              data: batchData,
+              format,
+              originalData: originalDocs,
+              req,
+              totalBatches,
+            })
+          : batchData
+
+      for (const row of dataToWrite) {
         if (format === 'csv') {
-          for (const key of Object.keys(transformedDoc)) {
+          for (const key of Object.keys(row)) {
             if (!columnsSet.has(key)) {
               columnsSet.add(key)
               columns.push(key)
@@ -232,7 +306,18 @@ export function createExportBatchProcessor(options: ExportBatchProcessorOptions
         }
       }
 
-      yield { columns: [...columns], docs: batchDocs }
+      yield { columns: [...columns], docs: dataToWrite }
+
+      if (hooks?.after && dataToWrite.length > 0) {
+        await hooks.after({
+          batchNumber,
+          data: dataToWrite,
+          format,
+          originalData: originalDocs,
+          req,
+          totalBatches,
+        })
+      }
 
       fetched += result.docs.length
       hasNextPage = result.hasNextPage && fetched < maxDocs