Performance Instrumentation

/**
 * Performance instrumentation and profiling class
 * Implements Disposable for automatic cleanup and reporting
 */
class Instrumentation implements Disposable {
  /**
   * Creates a new instrumentation instance
   * @param defaultFlush - Optional custom flush function for output (defaults to stderr)
   */
  constructor(defaultFlush?: (message: string) => void);

  /**
   * Records a hit counter for the given label
   * @param label - Identifier for the counter
   */
  hit(label: string): void;

  /**
   * Starts a timer with the given label
   * Supports nested timers with hierarchical labeling
   * @param label - Identifier for the timer
   */
  start(label: string): void;

  /**
   * Ends the most recently started timer with the given label
   * @param label - Identifier for the timer (must match the most recent start())
   * @throws Error if label doesn't match the most recent timer
   */
  end(label: string): void;

  /**
   * Resets all counters and timers
   * Clears all recorded data and timer stack
   */
  reset(): void;

  /**
   * Generates and outputs a performance report
   * @param flush - Optional custom output function (uses constructor default if not provided)
   */
  report(flush?: (message: string) => void): void;

  /**
   * Automatic cleanup method (Symbol.dispose)
   * Automatically calls report() if DEBUG environment variable is enabled
   */
  [Symbol.dispose](): void;
}

import { Instrumentation } from "@tailwindcss/node";

// Basic usage with automatic disposal
{
  using instrumentation = new Instrumentation();
  
  instrumentation.hit("process-start");
  
  instrumentation.start("compilation");
  // ... compilation work ...
  instrumentation.end("compilation");
  
  instrumentation.start("optimization");
  // ... optimization work ...
  instrumentation.end("optimization");
  
  // Report is automatically generated when exiting scope (if DEBUG=true)
}

// Manual reporting
const instrumentation = new Instrumentation();

instrumentation.start("build-process");

instrumentation.start("css-parsing");
// ... parsing work ...
instrumentation.end("css-parsing");

instrumentation.start("asset-processing");
// ... asset work ...
instrumentation.end("asset-processing");

instrumentation.end("build-process");

// Generate report manually
instrumentation.report();

// Custom output function
const logs: string[] = [];
instrumentation.report((message) => {
  logs.push(message);
});

import { Instrumentation } from "@tailwindcss/node";

const instrumentation = new Instrumentation();

instrumentation.start("build");
  instrumentation.start("compile");
    instrumentation.start("parse-css");
    instrumentation.end("parse-css");
    
    instrumentation.start("process-styles");  
    instrumentation.end("process-styles");
  instrumentation.end("compile");
  
  instrumentation.start("optimize");
  instrumentation.end("optimize");
instrumentation.end("build");

instrumentation.report();

// Output example:
// Timers:
// [  45.23ms] build × 1
// [  32.15ms]  ↳ compile × 1  
// [  12.80ms]   ↳ parse-css × 1
// [  18.45ms]   ↳ process-styles × 1
// [  11.08ms]  ↳ optimize × 1

import { Instrumentation } from "@tailwindcss/node";

const instrumentation = new Instrumentation();

// Track cache hits/misses
for (let i = 0; i < 100; i++) {
  if (cache.has(key)) {
    instrumentation.hit("cache-hit");
  } else {
    instrumentation.hit("cache-miss");
  }
}

instrumentation.report();

// Output example:
// Hits:
//   cache-hit × 85
//   cache-miss × 15

import { Instrumentation } from "@tailwindcss/node";

// Custom logger integration
const instrumentation = new Instrumentation((message) => {
  logger.debug(message);
});

// Or provide at report time
const metrics: string[] = [];
instrumentation.report((message) => {
  metrics.push(message);
  // Send to monitoring system
  sendToMonitoring(message);
});

import { env } from "@tailwindcss/node";

// When DEBUG environment variable is enabled, instrumentation
// automatically reports on disposal
if (env.DEBUG) {
  using instrumentation = new Instrumentation();
  // ... work ...
  // Report is automatically generated when scope exits
}

import { Instrumentation } from "@tailwindcss/node";

const instrumentation = new Instrumentation();

instrumentation.start("outer");
instrumentation.start("inner");

// This will throw an error - must end "inner" before "outer"
try {
  instrumentation.end("outer"); // Error: Mismatched timer label
} catch (error) {
  console.error(error.message);
  // Correct the order
  instrumentation.end("inner");
  instrumentation.end("outer");
}