feat: add NodeJSProfiler

Author: BioPhoton

packages/utils/docs/profiler.md

@@ -0,0 +1,255 @@
+# @code-pushup/utils - Profiler
+
+[![npm](https://img.shields.io/npm/v/%40code-pushup%2Futils.svg)](https://www.npmjs.com/package/@code-pushup/utils)
+[![downloads](https://img.shields.io/npm/dm/%40code-pushup%2Futils)](https://npmtrends.com/@code-pushup/utils)
+[![dependencies](https://img.shields.io/librariesio/release/npm/%40code-pushup/utils)](https://www.npmjs.com/package/@code-pushup/utils?activeTab=dependencies)
+
+⏱️ **High-performance profiling utility for structured timing measurements with Chrome DevTools Extensibility API payloads.** 📊
+
+---
+
+The `Profiler` class provides a clean, type-safe API for performance monitoring that integrates seamlessly with Chrome DevTools. It supports both synchronous and asynchronous operations with smart defaults for custom track visualization, enabling developers to track performance bottlenecks and optimize application speed.
+
+## Getting started
+
+1. If you haven't already, install [@code-pushup/utils](../../README.md).
+
+2. Install as a dependency with your package manager:
+
+   ```sh
+   npm install @code-pushup/utils
+   ```
+
+   ```sh
+   yarn add @code-pushup/utils
+   ```
+
+   ```sh
+   pnpm add @code-pushup/utils
+   ```
+
+3. Import and create a profiler instance:
+
+   ```ts
+   import { Profiler } from '@code-pushup/utils';
+
+   const profiler = new Profiler({
+     prefix: 'cp',
+     track: 'CLI',
+     trackGroup: 'Code Pushup',
+     color: 'primary-dark',
+     tracks: {
+       utils: { track: 'Utils', color: 'primary' },
+       core: { track: 'Core', color: 'primary-light' },
+     },
+     enabled: true,
+   });
+   ```
+
+4. Start measuring performance:
+
+   ```ts
+   // Measure synchronous operations
+   const result = profiler.measure('data-processing', () => {
+     return processData(data);
+   });
+
+   // Measure asynchronous operations
+   const asyncResult = await profiler.measureAsync('api-call', async () => {
+     return await fetch('/api/data').then(r => r.json());
+   });
+   ```
+
+## Configuration
+
+```ts
+new Profiler<T>(options: ProfilerOptions<T>)
+```
+
+**Parameters:**
+
+- `options` - Configuration options for the profiler instance
+
+**Options:**
+
+| Property     | Type      | Default     | Description                                                     |
+| ------------ | --------- | ----------- | --------------------------------------------------------------- |
+| `tracks`     | `object`  | `undefined` | Custom track configurations merged with defaults                |
+| `prefix`     | `string`  | `undefined` | Prefix for all measurement names                                |
+| `track`      | `string`  | `undefined` | Default track name for measurements                             |
+| `trackGroup` | `string`  | `undefined` | Default track group for organization                            |
+| `color`      | `string`  | `undefined` | Default color for track entries                                 |
+| `enabled`    | `boolean` | `env var`   | Whether profiling is enabled (defaults to CP_PROFILING env var) |
+
+### Environment Variables
+
+- `CP_PROFILING` - Enables or disables profiling globally (boolean)
+
+```bash
+# Enable profiling in development
+CP_PROFILING=true npm run dev
+
+# Disable profiling in production
+CP_PROFILING=false npm run build
+```
+
+## API Methods
+
+The profiler provides several methods for different types of performance measurements:
+
+### Synchronous measurements
+
+```ts
+profiler.measure<R>(event: string, work: () => R, options?: MeasureOptions<R>): R
+```
+
+Measures the execution time of a synchronous operation. Creates performance start/end marks and a final measure with Chrome DevTools Extensibility API payloads.
+
+```ts
+const result = profiler.measure(
+  'file-processing',
+  () => {
+    return fs.readFileSync('large-file.txt', 'utf8');
+  },
+  {
+    track: 'io-operations',
+    color: 'warning',
+  },
+);
+```
+
+### Asynchronous measurements
+
+```ts
+profiler.measureAsync<R>(event: string, work: () => Promise<R>, options?: MeasureOptions<R>): Promise<R>
+```
+
+Measures the execution time of an asynchronous operation.
+
+```ts
+const data = await profiler.measureAsync(
+  'api-request',
+  async () => {
+    const response = await fetch('/api/data');
+    return response.json();
+  },
+  {
+    track: 'network',
+    trackGroup: 'external',
+  },
+);
+```
+
+### Performance markers
+
+```ts
+profiler.marker(name: string, options?: EntryMeta & { color?: DevToolsColor }): void
+```
+
+Creates a performance mark with Chrome DevTools marker visualization. Markers appear as vertical lines spanning all tracks and can include custom metadata.
+
+```ts
+profiler.marker('user-action', {
+  color: 'secondary',
+  tooltipText: 'User clicked save button',
+  properties: [
+    ['action', 'save'],
+    ['elementId', 'save-btn'],
+  ],
+});
+```
+
+### Runtime control
+
+```ts
+profiler.setEnabled(enabled: boolean): void
+profiler.isEnabled(): boolean
+```
+
+Control profiling at runtime and check current status.
+
+```ts
+// Disable profiling temporarily
+profiler.setEnabled(false);
+
+// Check if profiling is active
+if (profiler.isEnabled()) {
+  console.log('Performance monitoring is active');
+}
+```
+
+## Examples
+
+### Basic usage
+
+```ts
+import { Profiler } from '@code-pushup/utils';
+
+const profiler = new Profiler({
+  prefix: 'cp',
+  track: 'CLI',
+  trackGroup: 'Code Pushup',
+  color: 'primary-dark',
+  tracks: {
+    utils: { track: 'Utils', color: 'primary' },
+    core: { track: 'Core', color: 'primary-light' },
+  },
+  enabled: true,
+});
+
+// Simple measurement
+const result = profiler.measure('data-transform', () => {
+  return transformData(input);
+});
+
+// Async measurement with custom options
+const data = await profiler.measureAsync(
+  'fetch-user',
+  async () => {
+    return await api.getUser(userId);
+  },
+  {
+    track: 'api',
+    color: 'info',
+  },
+);
+
+// Add a marker for important events
+profiler.marker('user-login', {
+  tooltipText: 'User authentication completed',
+});
+```
+
+### Custom tracks
+
+Define custom track configurations for better organization:
+
+```ts
+interface AppTracks {
+  api: ActionTrackEntryPayload;
+  db: ActionTrackEntryPayload;
+  cache: ActionTrackEntryPayload;
+}
+
+const profiler = new Profiler<AppTracks>({
+  tracks: {
+    api: { track: 'api', trackGroup: 'network', color: 'primary' },
+    db: { track: 'database', trackGroup: 'data', color: 'warning' },
+    cache: { track: 'cache', trackGroup: 'data', color: 'success' },
+  },
+});
+
+// Use predefined tracks
+const users = await profiler.measureAsync('fetch-users', fetchUsers, {
+  track: 'api',
+});
+
+const saved = profiler.measure('save-user', () => saveToDb(user), {
+  track: 'db',
+});
+```
+
+## Resources
+
+- **[Chrome DevTools Extensibility API](?)** - Official documentation for performance profiling
+- **[User Timing API](https://developer.mozilla.org/en-US/docs/Web/API/User_Timing_API)** - Web Performance API reference

packages/utils/mocks/sink.mock.ts

@@ -1,4 +1,8 @@
-import type { Sink } from '../src/lib/sink-source.type';
+import type {
+  RecoverResult,
+  Recoverable,
+  Sink,
+} from '../src/lib/sink-source.type';
 
 export class MockSink implements Sink<string, string> {
   private writtenItems: string[] = [];
@@ -28,3 +32,21 @@ export class MockSink implements Sink<string, string> {
     return [...this.writtenItems];
   }
 }
+
+export class MockRecoverableSink<T> extends MockSink implements Recoverable<T> {
+  recover(): RecoverResult<T> {
+    return {
+      records: this.getWrittenItems() as T[],
+      errors: [],
+      partialTail: null,
+    };
+  }
+
+  repack(): void {
+    this.getWrittenItems().forEach(item => this.write(item));
+  }
+
+  finalize(): void {
+    this.close();
+  }
+}

packages/utils/src/lib/exit-process.ts

@@ -44,8 +44,8 @@ export function installExitHandlers(options: ExitHandlerOptions = {}): void {
   const {
     onExit,
     onError,
-    exitOnFatal,
-    exitOnSignal,
+    exitOnFatal = false,
+    exitOnSignal = false,
     fatalExitCode = DEFAULT_FATAL_EXIT_CODE,
   } = options;
 

packages/utils/src/lib/performance-observer.ts

@@ -6,21 +6,31 @@ import {
 } from 'node:perf_hooks';
 import type { Buffered, Encoder, Observer, Sink } from './sink-source.type';
 
+/**
+ * Encoder that converts PerformanceEntry to domain events.
+ *
+ * Pure function that transforms performance entries into one or more domain events.
+ * Should be stateless, synchronous, and have no side effects.
+ */
+export type PerformanceEntryEncoder<F> = (
+  entry: PerformanceEntry,
+) => readonly F[];
+
 const OBSERVED_TYPES = ['mark', 'measure'] as const;
 type ObservedEntryType = 'mark' | 'measure';
 export const DEFAULT_FLUSH_THRESHOLD = 20;
 
 export type PerformanceObserverOptions<T> = {
   sink: Sink<T, unknown>;
-  encode: (entry: PerformanceEntry) => T[];
+  encodePerfEntry: PerformanceEntryEncoder<T>;
   buffered?: boolean;
   flushThreshold?: number;
 };
 
 export class PerformanceObserverSink<T>
-  implements Observer, Buffered, Encoder<PerformanceEntry, T[]>
+  implements Observer, Buffered, Encoder<PerformanceEntry, readonly T[]>
 {
-  #encode: (entry: PerformanceEntry) => T[];
+  #encodePerfEntry: PerformanceEntryEncoder<T>;
   #buffered: boolean;
   #flushThreshold: number;
   #sink: Sink<T, unknown>;
@@ -32,8 +42,8 @@ export class PerformanceObserverSink<T>
   #written: Map<ObservedEntryType, number>;
 
   constructor(options: PerformanceObserverOptions<T>) {
-    const { encode, sink, buffered, flushThreshold } = options;
-    this.#encode = encode;
+    const { encodePerfEntry, sink, buffered, flushThreshold } = options;
+    this.#encodePerfEntry = encodePerfEntry;
     this.#written = new Map<ObservedEntryType, number>(
       OBSERVED_TYPES.map(t => [t, 0]),
     );
@@ -42,14 +52,19 @@ export class PerformanceObserverSink<T>
     this.#flushThreshold = flushThreshold ?? DEFAULT_FLUSH_THRESHOLD;
   }
 
-  encode(entry: PerformanceEntry): T[] {
-    return this.#encode(entry);
+  encode(entry: PerformanceEntry): readonly T[] {
+    return this.#encodePerfEntry(entry);
   }
 
   subscribe(): void {
     if (this.#observer) {
       return;
     }
+    if (this.#sink.isClosed()) {
+      throw new Error(
+        'Sink must be opened before subscribing PerformanceObserver',
+      );
+    }
 
     // Only used to trigger the flush - it's not processing the entries, just counting them
     this.#observer = new PerformanceObserver(
@@ -76,6 +91,11 @@ export class PerformanceObserverSink<T>
     if (!this.#observer) {
       return;
     }
+    if (this.#sink.isClosed()) {
+      throw new Error(
+        'Sink must be opened before subscribing PerformanceObserver',
+      );
+    }
 
     OBSERVED_TYPES.forEach(t => {
       const written = this.#written.get(t) ?? 0;

packages/utils/src/lib/profiler/constants.ts

@@ -0,0 +1 @@
+export const PROFILER_ENABLED = 'CP_PROFILING';