feat: add profiling utilities for performance analysis (#16198)

## Summary

Adds lightweight profiling utilities for measuring execution time of
sync and async functions. This is a developer tool for debugging
performance issues during development — wrap any function with
`timeSync` or `timeAsync` to measure its duration, then call
`printProfileResults` to see a formatted table of timings.

Not intended for production use or to be imported by default, just
available when needed for performance investigations.

These utilities were used to generate results for:
- #16134
- #16129

Author: JarrodMFlesch

packages/payload/src/utilities/profiling.spec.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  clearProfiles,
+  getProfileResults,
+  printProfileResults,
+  timeAsync,
+  timeSync,
+} from './profiling.js'
+
+describe('Profiling Utilities', () => {
+  it('should time synchronous functions', () => {
+    clearProfiles()
+
+    const result = timeSync('syncOperation', () => {
+      let sum = 0
+      for (let i = 0; i < 1000; i++) {
+        sum += i
+      }
+      return sum
+    })
+
+    expect(result).toBe(499500)
+
+    const results = getProfileResults()
+    expect(results).toHaveLength(1)
+    expect(results[0]?.name).toBe('syncOperation')
+    expect(results[0]?.calls).toBe(1)
+    expect(results[0]?.duration).toBeGreaterThanOrEqual(0)
+  })
+
+  it('should time async functions', async () => {
+    clearProfiles()
+
+    const result = await timeAsync('asyncOperation', async () => {
+      await new Promise((resolve) => setTimeout(resolve, 10))
+      return 'done'
+    })
+
+    expect(result).toBe('done')
+
+    const results = getProfileResults()
+    expect(results).toHaveLength(1)
+    expect(results[0]?.name).toBe('asyncOperation')
+    expect(results[0]?.calls).toBe(1)
+    expect(results[0]?.duration).toBeGreaterThanOrEqual(9)
+  })
+
+  it('should accumulate multiple calls', () => {
+    clearProfiles()
+
+    for (let i = 0; i < 5; i++) {
+      timeSync('repeatedOperation', () => i * 2)
+    }
+
+    const results = getProfileResults()
+    expect(results).toHaveLength(1)
+    expect(results[0]?.calls).toBe(5)
+  })
+
+  it('should print profile results', () => {
+    clearProfiles()
+
+    timeSync('operation1', () => 'a')
+    timeSync('operation2', () => 'b')
+
+    // Just ensure it doesn't throw
+    printProfileResults()
+
+    const results = getProfileResults()
+    expect(results).toHaveLength(2)
+  })
+})

packages/payload/src/utilities/profiling.ts

@@ -0,0 +1,64 @@
+type ProfileEntry = {
+  calls: number
+  duration: number
+  name: string
+}
+
+const profiles = new Map<string, ProfileEntry>()
+const callStack: string[] = []
+
+export const timeSync = <T>(name: string, fn: () => T): T => {
+  callStack.push(name)
+  const start = performance.now()
+  try {
+    return fn()
+  } finally {
+    const duration = performance.now() - start
+    callStack.pop()
+    const entry = profiles.get(name) || { name, calls: 0, duration: 0 }
+    entry.duration += duration
+    entry.calls++
+    profiles.set(name, entry)
+  }
+}
+
+export const timeAsync = async <T>(name: string, fn: () => Promise<T>): Promise<T> => {
+  callStack.push(name)
+  const start = performance.now()
+  try {
+    return await fn()
+  } finally {
+    const duration = performance.now() - start
+    callStack.pop()
+    const entry = profiles.get(name) || { name, calls: 0, duration: 0 }
+    entry.duration += duration
+    entry.calls++
+    profiles.set(name, entry)
+  }
+}
+
+export const clearProfiles = () => {
+  profiles.clear()
+}
+
+export const printProfileResults = () => {
+  const entries = Array.from(profiles.values()).sort((a, b) => b.duration - a.duration)
+
+  console.log('\n=== Profile Results ===')
+  console.log('Name'.padEnd(50) + 'Duration (ms)'.padStart(15) + 'Calls'.padStart(10))
+  console.log('-'.repeat(75))
+
+  for (const entry of entries) {
+    console.log(
+      entry.name.padEnd(50) +
+        entry.duration.toFixed(2).padStart(15) +
+        String(entry.calls).padStart(10),
+    )
+  }
+
+  console.log('='.repeat(75) + '\n')
+}
+
+export const getProfileResults = () => {
+  return Array.from(profiles.values()).sort((a, b) => b.duration - a.duration)
+}