feat: add typescript.postProcess hook for type generation (#16103)

## Summary

This pr would allow us to import a generic from the plugin and then use
it. The limitation with json-schema-to-typescript is the inability to
generate a type in the file that takes generics.

There are some generated generics plopped in, internally by our
addSelectGenericsToGeneratedTypes function.

This PR exposes a way for external plugins to manipulate the generated
config post-processing of json-schema-to-typescript which is not
possible today.

## Implementation

In `packages/payload/src/bin/generateTypes.ts`, after
`addSelectGenericsToGeneratedTypes`:

```ts
if (config.typescript?.postProcess?.length) {
  for (const fn of config.typescript.postProcess) {
    compiled = fn(compiled);
  }
}
```

Add to TypeScript config type:
```ts
typescript?: {
  postProcess?: Array<(compiled: string) => string>;
}
```

**Use cases**

- Inject imports from plugin packages
- Add utility types

**Example**

```ts
// Plugin adds an import and uses it via tsType on fields

typescript: {
  postProcess: [
    ...(config.typescript?.postProcess || []),
    (compiled) => {
      const importStmt = `import type { MyPluginType } from '@payloadcms/my-plugin';`;
      return compiled.replace(/(\/\*[\s\S]*?\*\/\n)/, `$1\n${importStmt}\n`);
    },
  ],
}
```

**Notes**

- Follows existing pattern (Payload already post-processes for Select
generics)

Author: JarrodMFlesch

packages/payload/src/bin/generateTypes.ts

@@ -50,6 +50,12 @@ export async function generateTypes(
 
   compiled = addSelectGenericsToGeneratedTypes({ compiledGeneratedTypes: compiled })
 
+  if (config.typescript.postProcess?.length) {
+    for (const fn of config.typescript.postProcess) {
+      compiled = fn({ compiledTypes: compiled, config })
+    }
+  }
+
   if (config.typescript.declare !== false) {
     if (config.typescript.declare?.ignoreTSError) {
       compiled += `\n\n${declareWithTSIgnoreError}`

packages/payload/src/config/types.ts

@@ -1486,6 +1486,24 @@ export type Config = {
     /** Filename to write the generated types to */
     outputFile?: string
 
+    /**
+     * Post-process the generated TypeScript types string before writing to file.
+     * Useful for plugins that need to inject generic types that JSON Schema cannot express.
+     *
+     * Functions are applied in order after the built-in Select generics are added.
+     *
+     * @example
+     * ```ts
+     * postProcess: [
+     *   ({ compiledTypes, config }) => {
+     *     const genericType = `export type MyGeneric<T> = { value: T };`
+     *     return compiledTypes.replace(/(\/\*[\s\S]*?\*\/\n)/, `$1\n${genericType}\n`)
+     *   },
+     * ]
+     * ```
+     */
+    postProcess?: Array<(args: { compiledTypes: string; config: SanitizedConfig }) => string>
+
     /**
      * Allows you to modify the base JSON schema that is generated during generate:types. This JSON schema will be used
      * to generate the TypeScript interfaces.

test/types/config.ts

@@ -171,5 +171,19 @@ export default buildConfigWithDefaults({
   typescript: {
     outputFile: path.resolve(dirname, 'payload-types.ts'),
     strictDraftTypes: true,
+    postProcess: [
+      ({ compiledTypes }) => {
+        const genericType = `export type TestPluginGeneric<T> = { value: T };`
+        // Insert after banner comment
+        return compiledTypes.replace(/(\/\*[\s\S]*?\*\/\n)/, `$1\n${genericType}\n`)
+      },
+      ({ compiledTypes }) => {
+        // Second function adds another type after the first
+        return compiledTypes.replace(
+          'export type TestPluginGeneric<T>',
+          'export type SecondGeneric<K, V> = { key: K; value: V };\nexport type TestPluginGeneric<T>',
+        )
+      },
+    ],
   },
 })

test/types/int.spec.ts

@@ -0,0 +1,33 @@
+import fs from 'fs/promises'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { describe, expect, it } from 'vitest'
+
+const dirname = path.dirname(fileURLToPath(import.meta.url))
+
+describe('typescript.postProcess', () => {
+  it('should apply postProcess functions to generated types', async () => {
+    const outputFile = path.resolve(dirname, 'payload-types.ts')
+    const content = await fs.readFile(outputFile, 'utf-8')
+
+    // Verify custom types were injected by postProcess
+    expect(content).toContain('export type TestPluginGeneric<T> = { value: T };')
+    expect(content).toContain('export type SecondGeneric<K, V> = { key: K; value: V };')
+  })
+
+  it('should apply multiple postProcess functions in order', async () => {
+    const outputFile = path.resolve(dirname, 'payload-types.ts')
+    const content = await fs.readFile(outputFile, 'utf-8')
+
+    // SecondGeneric (from second function) should appear before TestPluginGeneric
+    // because the second function prepends to TestPluginGeneric
+    const secondIndex = content.indexOf('SecondGeneric')
+    const firstIndex = content.indexOf('TestPluginGeneric')
+    const configIndex = content.indexOf('export interface Config')
+
+    expect(secondIndex).toBeGreaterThan(-1)
+    expect(firstIndex).toBeGreaterThan(-1)
+    expect(secondIndex).toBeLessThan(firstIndex)
+    expect(firstIndex).toBeLessThan(configIndex)
+  })
+})

test/types/payload-types.ts

@@ -1,4 +1,7 @@
 /* tslint:disable */
+
+export type SecondGeneric<K, V> = { key: K; value: V };
+export type TestPluginGeneric<T> = { value: T };
 /* eslint-disable */
 /**
  * This file was automatically generated by Payload.
@@ -116,6 +119,9 @@ export interface Config {
     settings: SettingsSelect<false> | SettingsSelect<true>;
   };
   locale: null;
+  widgets: {
+    collections: CollectionsWidget;
+  };
   strictDraftTypes: true;
   user: User;
   jobs: {
@@ -482,6 +488,16 @@ export interface SettingsSelect<T extends boolean = true> {
   createdAt?: T;
   globalType?: T;
 }
+/**
+ * This interface was referenced by `Config`'s JSON-Schema
+ * via the `definition` "collections_widget".
+ */
+export interface CollectionsWidget {
+  data?: {
+    [k: string]: unknown;
+  };
+  width: 'full';
+}
 /**
  * This interface was referenced by `Config`'s JSON-Schema
  * via the `definition` "auth".