feat: add profiler class

Author: John Doe

packages/utils/src/lib/profiler/profiler.int.test.ts

@@ -7,7 +7,6 @@ describe('Profiler Integration', () => {
   let profiler: Profiler<Record<string, ActionTrackEntryPayload>>;
 
   beforeEach(() => {
-    // Clear all performance entries before each test
     performance.clearMarks();
     performance.clearMeasures();
 
@@ -19,7 +18,7 @@ describe('Profiler Integration', () => {
         async: { track: 'async-ops', color: 'secondary' },
         sync: { track: 'sync-ops', color: 'tertiary' },
       },
-      enabled: true, // Explicitly enable for integration tests
+      enabled: true,
     });
   });
 
@@ -33,18 +32,17 @@ describe('Profiler Integration', () => {
 
     expect(result).toBe(499_500);
 
-    // Verify performance entries were created
     const marks = performance.getEntriesByType('mark');
     const measures = performance.getEntriesByType('measure');
 
-    expect(marks).toEqual(
+    expect(marks).toStrictEqual(
       expect.arrayContaining([
         expect.objectContaining({ name: 'test:sync-test:start' }),
         expect.objectContaining({ name: 'test:sync-test:end' }),
       ]),
     );
 
-    expect(measures).toEqual(
+    expect(measures).toStrictEqual(
       expect.arrayContaining([
         expect.objectContaining({
           name: 'test:sync-test',
@@ -56,25 +54,23 @@ describe('Profiler Integration', () => {
 
   it('should create complete performance timeline for async operation', async () => {
     const result = await profiler.measureAsync('async-test', async () => {
-      // Simulate async work
       await new Promise(resolve => setTimeout(resolve, 10));
       return 'async-result';
     });
 
     expect(result).toBe('async-result');
 
-    // Verify performance entries were created
     const marks = performance.getEntriesByType('mark');
     const measures = performance.getEntriesByType('measure');
 
-    expect(marks).toEqual(
+    expect(marks).toStrictEqual(
       expect.arrayContaining([
         expect.objectContaining({ name: 'test:async-test:start' }),
         expect.objectContaining({ name: 'test:async-test:end' }),
       ]),
     );
 
-    expect(measures).toEqual(
+    expect(measures).toStrictEqual(
       expect.arrayContaining([
         expect.objectContaining({
           name: 'test:async-test',
@@ -93,10 +89,9 @@ describe('Profiler Integration', () => {
     const marks = performance.getEntriesByType('mark');
     const measures = performance.getEntriesByType('measure');
 
-    expect(marks).toHaveLength(4); // 2 for outer + 2 for inner
-    expect(measures).toHaveLength(2); // 1 for outer + 1 for inner
+    expect(marks).toHaveLength(4);
+    expect(measures).toHaveLength(2);
 
-    // Check all marks exist
     const markNames = marks.map(m => m.name);
     expect(markNames).toStrictEqual(
       expect.arrayContaining([
@@ -107,7 +102,6 @@ describe('Profiler Integration', () => {
       ]),
     );
 
-    // Check all measures exist
     const measureNames = measures.map(m => m.name);
     expect(measureNames).toStrictEqual(
       expect.arrayContaining(['test:outer', 'test:inner']),
@@ -125,7 +119,7 @@ describe('Profiler Integration', () => {
     });
 
     const marks = performance.getEntriesByType('mark');
-    expect(marks).toEqual(
+    expect(marks).toStrictEqual(
       expect.arrayContaining([
         expect.objectContaining({
           name: 'test-marker',
@@ -146,15 +140,15 @@ describe('Profiler Integration', () => {
   });
 
   it('should create proper DevTools payloads for tracks', () => {
-    profiler.measure('track-test', () => 'result', {
+    profiler.measure('track-test', (): string => 'result', {
       success: result => ({
         properties: [['result', result]],
         tooltipText: 'Track test completed',
       }),
     });
 
     const measures = performance.getEntriesByType('measure');
-    expect(measures).toEqual(
+    expect(measures).toStrictEqual(
       expect.arrayContaining([
         expect.objectContaining({
           detail: {
@@ -172,7 +166,6 @@ describe('Profiler Integration', () => {
   });
 
   it('should merge track defaults with measurement options', () => {
-    // Use the sync track from our configuration
     profiler.measure('sync-op', () => 'sync-result', {
       success: result => ({
         properties: [
@@ -183,14 +176,14 @@ describe('Profiler Integration', () => {
     });
 
     const measures = performance.getEntriesByType('measure');
-    expect(measures).toEqual(
+    expect(measures).toStrictEqual(
       expect.arrayContaining([
         expect.objectContaining({
           detail: {
             devtools: expect.objectContaining({
               dataType: 'track-entry',
-              track: 'integration-tests', // default track
-              color: 'primary', // default color
+              track: 'integration-tests',
+              color: 'primary',
               properties: [
                 ['operation', 'sync'],
                 ['result', 'sync-result'],
@@ -212,7 +205,7 @@ describe('Profiler Integration', () => {
     }).toThrow(error);
 
     const measures = performance.getEntriesByType('measure');
-    expect(measures).toEqual(
+    expect(measures).toStrictEqual(
       expect.arrayContaining([
         expect.objectContaining({
           detail: {
@@ -239,7 +232,7 @@ describe('Profiler Integration', () => {
     }).toThrow(customError);
 
     const measures = performance.getEntriesByType('measure');
-    expect(measures).toEqual(
+    expect(measures).toStrictEqual(
       expect.arrayContaining([
         expect.objectContaining({
           detail: {
@@ -264,21 +257,17 @@ describe('Profiler Integration', () => {
       enabled: false,
     });
 
-    // Test sync measurement
     const syncResult = disabledProfiler.measure('disabled-sync', () => 'sync');
     expect(syncResult).toBe('sync');
 
-    // Test async measurement
     const asyncResult = disabledProfiler.measureAsync(
       'disabled-async',
       async () => 'async',
     );
     await expect(asyncResult).resolves.toBe('async');
 
-    // Test marker
     disabledProfiler.marker('disabled-marker');
 
-    // Verify no performance entries were created
     expect(performance.getEntriesByType('mark')).toHaveLength(0);
     expect(performance.getEntriesByType('measure')).toHaveLength(0);
   });

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

@@ -1,37 +1,31 @@
 import process from 'node:process';
 import { isEnvVarEnabled } from '../env.js';
 import {
+  type MeasureCtxOptions,
   type MeasureOptions,
   asOptions,
   markerPayload,
   measureCtx,
   setupTracks,
 } from '../user-timing-extensibility-api-utils.js';
 import type {
-  ActionColorPayload,
   ActionTrackEntryPayload,
   DevToolsColor,
   EntryMeta,
-  TrackMeta,
 } from '../user-timing-extensibility-api.type.js';
 import { PROFILER_ENABLED } from './constants.js';
 
-/** Default track configuration combining metadata and color options. */
-type DefaultTrackOptions = TrackMeta & ActionColorPayload;
-
 /**
  * Configuration options for creating a Profiler instance.
  *
  * @template T - Record type defining available track names and their configurations
  */
 type ProfilerMeasureOptions<T extends Record<string, ActionTrackEntryPayload>> =
-  DefaultTrackOptions & {
+  MeasureCtxOptions & {
     /** Custom track configurations that will be merged with default settings */
-    tracks: Record<keyof T, Partial<ActionTrackEntryPayload>>;
+    tracks?: Record<keyof T, Partial<ActionTrackEntryPayload>>;
     /** Whether profiling should be enabled (defaults to CP_PROFILING env var) */
     enabled?: boolean;
-    /** Prefix for all performance measurement names to avoid conflicts */
-    prefix: string;
   };
 
 /**
@@ -51,38 +45,11 @@ export type ProfilerOptions<T extends Record<string, ActionTrackEntryPayload>> =
  * integration for Chrome DevTools Performance panel. It supports both synchronous and
  * asynchronous operations with customizable track visualization.
  *
- * @example
- * ```typescript
- * const profiler = new Profiler({
- *   prefix: 'api',
- *   track: 'backend-calls',
- *   trackGroup: 'api',
- *   color: 'secondary',
- *   tracks: {
- *     database: { track: 'database', color: 'tertiary' },
- *     external: { track: 'external-apis', color: 'primary' }
- *   }
- * });
- *
- * // Measure synchronous operation
- * const result = profiler.measure('fetch-user', () => api.getUser(id));
- *
- * // Measure async operation
- * const asyncResult = await profiler.measureAsync('save-data',
- *   () => api.saveData(data)
- * );
- *
- * // Add marker
- * profiler.marker('cache-invalidated', {
- *   color: 'warning',
- *   tooltipText: 'Cache cleared due to stale data'
- * });
- * ```
  */
 export class Profiler<T extends Record<string, ActionTrackEntryPayload>> {
   #enabled: boolean;
   private readonly defaults: ActionTrackEntryPayload;
-  readonly tracks: Record<keyof T, ActionTrackEntryPayload>;
+  readonly tracks: Record<keyof T, ActionTrackEntryPayload> | undefined;
   private readonly ctxOf: ReturnType<typeof measureCtx>;
 
   /**
@@ -96,28 +63,16 @@ export class Profiler<T extends Record<string, ActionTrackEntryPayload>> {
    * @param options.color - Default color for track entries
    * @param options.enabled - Whether profiling is enabled (defaults to CP_PROFILING env var)
    *
-   * @example
-   * ```typescript
-   * const profiler = new Profiler({
-   *   prefix: 'api',
-   *   track: 'backend-calls',
-   *   trackGroup: 'api',
-   *   color: 'secondary',
-   *   enabled: true,
-   *   tracks: {
-   *     database: { track: 'database', color: 'tertiary' },
-   *     cache: { track: 'cache', color: 'primary' }
-   *   }
-   * });
-   * ```
    */
   constructor(options: ProfilerOptions<T>) {
     const { tracks, prefix, enabled, ...defaults } = options;
     const dataType = 'track-entry';
 
     this.#enabled = enabled ?? isEnvVarEnabled(PROFILER_ENABLED);
     this.defaults = { ...defaults, dataType };
-    this.tracks = setupTracks({ ...defaults, dataType }, tracks);
+    this.tracks = tracks
+      ? setupTracks({ ...defaults, dataType }, tracks)
+      : undefined;
     this.ctxOf = measureCtx({
       ...defaults,
       dataType,
@@ -157,13 +112,12 @@ export class Profiler<T extends Record<string, ActionTrackEntryPayload>> {
    * returns immediately without creating any performance entries.
    *
    * @param name - Unique name for the marker
-   * @param opt - Optional metadata and styling for the marker
+   * @param opt - Metadata and styling for the marker
    * @param opt.color - Color of the marker line (defaults to profiler default)
    * @param opt.tooltipText - Text shown on hover
    * @param opt.properties - Key-value pairs for detailed view
    *
    * @example
-   * ```typescript
    * profiler.marker('user-action-start', {
    *   color: 'primary',
    *   tooltipText: 'User clicked save button',
@@ -172,7 +126,6 @@ export class Profiler<T extends Record<string, ActionTrackEntryPayload>> {
    *     ['elementId', 'save-btn']
    *   ]
    * });
-   * ```
    */
   marker(name: string, opt?: EntryMeta & { color: DevToolsColor }) {
     if (!this.#enabled) {
@@ -201,26 +154,19 @@ export class Profiler<T extends Record<string, ActionTrackEntryPayload>> {
    * @template R - The return type of the work function
    * @param event - Name for this measurement event
    * @param work - Function to execute and measure
-   * @param options - Optional measurement configuration overrides
+   * @param options - Measurement configuration overrides
    * @returns The result of the work function
    *
-   * @example
-   * ```typescript
-   * const user = profiler.measure('fetch-user', () => {
-   *   return api.getUser(userId);
-   * }, {
-   *   success: (result) => ({
-   *     properties: [['userId', result.id], ['loadTime', Date.now()]]
-   *   })
-   * });
-   * ```
    */
-  measure<R>(event: string, work: () => R, options?: MeasureOptions): R {
+  measure<R>(event: string, work: () => R, options?: MeasureOptions<R>): R {
     if (!this.#enabled) {
       return work();
     }
 
-    const { start, success, error } = this.ctxOf(event, options);
+    const { start, success, error } = this.ctxOf(
+      event,
+      options as MeasureOptions,
+    );
     start();
     try {
       const r = work();
@@ -242,34 +188,23 @@ export class Profiler<T extends Record<string, ActionTrackEntryPayload>> {
    * @template R - The resolved type of the work promise
    * @param event - Name for this measurement event
    * @param work - Function returning a promise to execute and measure
-   * @param options - Optional measurement configuration overrides
+   * @param options - Measurement configuration overrides
    * @returns Promise that resolves to the result of the work function
    *
-   * @example
-   * ```typescript
-   * const data = await profiler.measureAsync('save-form', async () => {
-   *   const result = await api.saveForm(formData);
-   *   return result;
-   * }, {
-   *   success: (result) => ({
-   *     properties: [['recordsSaved', result.count]]
-   *   }),
-   *   error: (err) => ({
-   *     properties: [['errorType', err.name]]
-   *   })
-   * });
-   * ```
    */
   async measureAsync<R>(
     event: string,
     work: () => Promise<R>,
-    options?: MeasureOptions,
+    options?: MeasureOptions<R>,
   ): Promise<R> {
     if (!this.#enabled) {
       return await work();
     }
 
-    const { start, success, error } = this.ctxOf(event, options);
+    const { start, success, error } = this.ctxOf(
+      event,
+      options as MeasureOptions,
+    );
     start();
     try {
       const r = work();