Function measureMemoryOperation

benchmark/performance.js:214–303

* Measure GC pressure for an async operation over multiple iterations. * Tracks total garbage collection time per operation using PerformanceObserver. * Using total GC time (sum of all pauses) rather than max single pause provides * much more stable metrics — it eliminates the variance from V8 ch

({ name, operation, iterations, skipWarmup = false })

 * @param {boolean} [options.skipWarmup=false] Skip warmup phase.
 */
async function measureMemoryOperation({ name, operation, iterations, skipWarmup = false }) {
  const { PerformanceObserver } = require('node:perf_hooks');

  // Override iterations if global ITERATIONS is set
  iterations = ITERATIONS || iterations;

  // Determine warmup count (20% of iterations)
  const warmupCount = skipWarmup ? 0 : Math.floor(iterations * 0.2);
  const gcDurations = [];

  if (warmupCount > 0) {
    logInfo(`Starting warmup phase of ${warmupCount} iterations...`);
    for (let i = 0; i < warmupCount; i++) {
      await operation();
    }
    logInfo('Warmup complete.');
  }

  // Measurement phase
  logInfo(`Starting measurement phase of ${iterations} iterations...`);
  const progressInterval = Math.ceil(iterations / 10);

  for (let i = 0; i < iterations; i++) {
    // Force GC before each iteration to start from a clean state
    if (typeof global.gc === 'function') {
      global.gc();
    }

    // Track GC events during this iteration; sum all GC pause durations to
    // measure total GC work, which is stable regardless of whether V8 chooses
    // one long pause or many short pauses
    let totalGcTime = 0;
    const obs = new PerformanceObserver((list) => {
      for (const entry of list.getEntries()) {
        totalGcTime += entry.duration;
      }
    });
    obs.observe({ type: 'gc', buffered: false });

    await operation();

    // Force GC after the operation to flush pending GC work into this
    // iteration's measurement, preventing cross-iteration contamination
    if (typeof global.gc === 'function') {
      global.gc();
    }

    // Flush any buffered entries before disconnecting to avoid data loss
    for (const entry of obs.takeRecords()) {
      totalGcTime += entry.duration;
    }
    obs.disconnect();
    gcDurations.push(totalGcTime);

    if (LOG_ITERATIONS) {
      logInfo(`Iteration ${i + 1}: ${totalGcTime.toFixed(2)} ms GC`);
    } else if ((i + 1) % progressInterval === 0 || i + 1 === iterations) {
      const progress = Math.round(((i + 1) / iterations) * 100);