refactor: wip

Author: BioPhoton

packages/utils/eslint.config.js

@@ -12,6 +12,13 @@ export default tseslint.config(
       },
     },
   },
+  {
+    files: ['packages/utils/src/lib/**/file-sink*.ts'],
+    rules: {
+      'n/no-sync': 'off',
+      eqeqeq: 'off',
+    },
+  },
   {
     files: ['**/*.json'],
     rules: {

packages/utils/src/lib/file-sink.ts

@@ -1,4 +1,4 @@
-import * as fs from 'node:fs';
+import fs from 'node:fs';
 import path from 'node:path';
 import type { Decoder, Encoder } from './sink-source.type';
 
@@ -67,7 +67,11 @@ export class AppendFileSink {
       .map(line => (line.endsWith('\r') ? line.slice(0, -1) : line));
   }
 
-  recover() {
+  recover(): {
+    records: string[];
+    errors: { lineNo: number; line: string; error: Error }[];
+    partialTail: string | null;
+  } {
     if (!fs.existsSync(this.filePath)) {
       return { records: [], errors: [], partialTail: null };
     }
@@ -131,7 +135,11 @@ export class JsonlFile<T> {
     yield* [...this.sink.readAll()].map(line => this.decode(line));
   }
 
-  recover() {
+  recover(): {
+    records: T[];
+    errors: { lineNo: number; line: string; error: Error }[];
+    partialTail: string | null;
+  } {
     const r = this.sink.recover();
     return {
       records: r.records.map(l => this.decode(l)),

packages/utils/src/lib/profiler/file-sink-json-trace.ts

@@ -28,7 +28,7 @@ export type FinalizeTraceFileOptions = {
   marginDurMs?: number;
 };
 
-// eslint-disable-next-line max-lines-per-function
+// eslint-disable-next-line max-lines-per-function, complexity
 export function finalizeTraceFile(
   events: (SpanEvent | InstantEvent)[],
   outputPath: string,

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

@@ -1,6 +1,5 @@
+import process from 'node:process';
 import { isEnvVarEnabled } from '../env.js';
-import { PerformanceObserverSink } from '../performance-observer.js';
-import type { Recoverable, Sink } from '../sink-source.type.js';
 import {
   type ActionTrackConfigs,
   type MeasureCtxOptions,
@@ -96,22 +95,20 @@ export class Profiler<T extends ActionTrackConfigs> {
   /**
    * Sets enabled state for this profiler.
    *
-   * Note: This only affects the current profiler instance and does not modify environment variables.
-   * Environment variables are read-only configuration that should be set before application startup.
+   * Also sets the `CP_PROFILING` environment variable.
+   * This means any future {@link Profiler} instantiations (including child processes) will use the same enabled state.
    *
    * @param enabled - Whether profiling should be enabled
    */
   setEnabled(enabled: boolean): void {
-    if (this.#enabled === enabled) {
-      return;
-    }
+    process.env[PROFILER_ENABLED_ENV_VAR] = `${enabled}`;
     this.#enabled = enabled;
   }
 
   /**
    * Is profiling enabled?
    *
-   * Profiling is enabled by {@link setEnabled} call or by the `CP_PROFILING` environment variable at instantiation.
+   * Profiling is enabled by {@link setEnabled} call or `CP_PROFILING` environment variable.
    *
    * @returns Whether profiling is currently enabled
    */
@@ -229,108 +226,3 @@ export class Profiler<T extends ActionTrackConfigs> {
     }
   }
 }
-
-/**
- * Options for configuring a NodejsProfiler instance.
- *
- * Extends ProfilerOptions with a required sink parameter.
- *
- * @template Tracks - Record type defining available track names and their configurations
- */
-export type NodejsProfilerOptions<
-  DomainEvents,
-  Tracks extends Record<string, ActionTrackEntryPayload>,
-> = ProfilerOptions<Tracks> & {
-  /** Sink for buffering and flushing performance data */
-  sink: Sink<DomainEvents, unknown> & Recoverable<unknown>;
-  /** Encoder that converts PerformanceEntry to domain events */
-  // eslint-disable-next-line n/no-unsupported-features/node-builtins
-  encode: (entry: PerformanceEntry) => DomainEvents[];
-};
-
-/**
- * Performance profiler with automatic process exit handling for buffered performance data.
- *
- * This class extends the base {@link Profiler} with automatic flushing of performance data
- * when the process exits. It accepts a {@link PerformanceObserverSink} that buffers performance
- * entries and ensures they are written out during process termination, even for unexpected exits.
- *
- * The sink defines the output format for performance data, enabling flexible serialization
- * to various formats such as DevTools TraceEvent JSON, OpenTelemetry protocol buffers,
- * or custom domain-specific formats.
- *
- * The profiler automatically subscribes to the performance observer when enabled and installs
- * exit handlers that flush buffered data on process termination (signals, fatal errors, or normal exit).
- *
- */
-export class NodejsProfiler<
-  DomainEvents,
-  Tracks extends Record<string, ActionTrackEntryPayload> = Record<
-    string,
-    ActionTrackEntryPayload
-  >,
-> extends Profiler<Tracks> {
-  #sink: Sink<DomainEvents, unknown> & Recoverable<unknown>;
-  #performanceObserverSink: PerformanceObserverSink<DomainEvents>;
-
-  /**
-   * Creates a new NodejsProfiler instance with automatic exit handling.
-   *
-   * @param options - Configuration options including the sink
-   * @param options.sink - Sink for buffering and flushing performance data
-   * @param options.tracks - Custom track configurations merged with defaults
-   * @param options.prefix - Prefix for all measurement names
-   * @param options.track - Default track name for measurements
-   * @param options.trackGroup - Default track group for organization
-   * @param options.color - Default color for track entries
-   * @param options.enabled - Whether profiling is enabled (defaults to CP_PROFILING env var)
-   *
-   */
-  constructor(options: NodejsProfilerOptions<DomainEvents, Tracks>) {
-    const { sink, encode, ...profilerOptions } = options;
-
-    super(profilerOptions);
-
-    this.#sink = sink;
-
-    this.#performanceObserverSink = new PerformanceObserverSink<DomainEvents>({
-      sink,
-      encode,
-    });
-
-    this.#setObserving(this.isEnabled());
-  }
-
-  #setObserving(observing: boolean): void {
-    if (observing) {
-      this.#sink.open();
-      this.#performanceObserverSink.subscribe();
-    } else {
-      this.#performanceObserverSink.unsubscribe();
-      this.#performanceObserverSink.flush();
-      this.#sink.close();
-    }
-  }
-
-  /**
-   * Sets enabled state for this profiler and manages sink/observer lifecycle.
-   *
-   * Design: Environment = default, Runtime = override
-   * - Environment variables define defaults (read once at construction)
-   * - This method provides runtime control without mutating globals
-   * - Child processes are unaffected by runtime enablement changes
-   *
-   * Invariant: enabled ↔ sink + observer state
-   * - enabled === true  → sink open + observer subscribed
-   * - enabled === false → sink closed + observer unsubscribed
-   *
-   * @param enabled - Whether profiling should be enabled
-   */
-  setEnabled(enabled: boolean): void {
-    if (this.isEnabled() === enabled) {
-      return;
-    }
-    super.setEnabled(enabled);
-    this.#setObserving(enabled);
-  }
-}

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

@@ -128,12 +128,12 @@ describe('Profiler', () => {
     expect(profiler.isEnabled()).toBe(false);
   });
 
-  it('setEnabled should update internal state without affecting env vars', () => {
+  it('isEnabled should update environment variable', () => {
     profiler.setEnabled(true);
-    expect(profiler.isEnabled()).toBe(true);
+    expect(process.env.CP_PROFILING).toBe('true');
 
     profiler.setEnabled(false);
-    expect(profiler.isEnabled()).toBe(false);
+    expect(process.env.CP_PROFILING).toBe('false');
   });
 
   it('marker should execute without error when enabled', () => {
@@ -423,22 +423,4 @@ describe('Profiler', () => {
     ).rejects.toThrow(error);
     expect(workFn).toHaveBeenCalled();
   });
-
-  it('setEnabled should be idempotent', () => {
-    // Test enabling
-    profiler.setEnabled(true);
-    expect(profiler.isEnabled()).toBe(true);
-
-    // Setting to true again should not change anything
-    profiler.setEnabled(true);
-    expect(profiler.isEnabled()).toBe(true);
-
-    // Test disabling
-    profiler.setEnabled(false);
-    expect(profiler.isEnabled()).toBe(false);
-
-    // Setting to false again should not change anything
-    profiler.setEnabled(false);
-    expect(profiler.isEnabled()).toBe(false);
-  });
 });

packages/utils/src/lib/sink-source.type.ts

@@ -7,6 +7,7 @@ export type EncoderInterface<I, O> = {
   encode: (input: I) => O;
 };
 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
 export type Sink<I = string | Buffer, O = unknown> = {
   setPath: (filePath: string) => void;
   getPath: () => string;