@code-pushup/utils 0.110.0 → 0.111.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@code-pushup/utils",
-  "version": "0.110.0",
+  "version": "0.111.1",
   "description": "Low-level utilities (helper functions, etc.) used by Code PushUp CLI",
   "license": "MIT",
   "homepage": "https://github.com/code-pushup/cli/tree/main/packages/utils#readme",
@@ -27,7 +27,7 @@
     "node": ">=18.2.0"
   },
   "dependencies": {
-    "@code-pushup/models": "0.110.0",
+    "@code-pushup/models": "0.111.1",
     "ansis": "^3.3.0",
     "build-md": "^0.4.2",
     "bundle-require": "^5.1.0",

package/src/lib/exit-process.d.ts

@@ -18,4 +18,14 @@ export type ExitHandlerOptions = {
     exitOnSignal?: boolean;
     fatalExitCode?: number;
 };
-export declare function installExitHandlers(options?: ExitHandlerOptions): void;
+/**
+ *
+ * @param options - Options for the exit handler
+ * @param options.onExit - Callback to be called when the process exits
+ * @param options.onError - Callback to be called when an error occurs
+ * @param options.exitOnFatal - Whether to exit the process on fatal errors
+ * @param options.exitOnSignal - Whether to exit the process on signals
+ * @param options.fatalExitCode - The exit code to use for fatal errors
+ * @returns A function to unsubscribe from the exit handlers
+ */
+export declare function subscribeProcessExit(options?: ExitHandlerOptions): () => void;

package/src/lib/exit-process.js

@@ -16,10 +16,21 @@ export const SIGNAL_EXIT_CODES = () => {
     };
 };
 export const DEFAULT_FATAL_EXIT_CODE = 1;
-export function installExitHandlers(options = {}) {
+/**
+ *
+ * @param options - Options for the exit handler
+ * @param options.onExit - Callback to be called when the process exits
+ * @param options.onError - Callback to be called when an error occurs
+ * @param options.exitOnFatal - Whether to exit the process on fatal errors
+ * @param options.exitOnSignal - Whether to exit the process on signals
+ * @param options.fatalExitCode - The exit code to use for fatal errors
+ * @returns A function to unsubscribe from the exit handlers
+ */
+// eslint-disable-next-line max-lines-per-function
+export function subscribeProcessExit(options = {}) {
     // eslint-disable-next-line functional/no-let
     let closedReason;
-    const { onExit, onError, exitOnFatal, exitOnSignal, fatalExitCode = DEFAULT_FATAL_EXIT_CODE, } = options;
+    const { onExit, onError, exitOnFatal = false, exitOnSignal = false, fatalExitCode = DEFAULT_FATAL_EXIT_CODE, } = options;
     const close = (code, reason) => {
         if (closedReason) {
             return;
@@ -27,7 +38,7 @@ export function installExitHandlers(options = {}) {
         closedReason = reason;
         onExit?.(code, reason);
     };
-    process.on('uncaughtException', err => {
+    const uncaughtExceptionHandler = (err) => {
         onError?.(err, 'uncaughtException');
         if (exitOnFatal) {
             close(fatalExitCode, {
@@ -35,8 +46,8 @@ export function installExitHandlers(options = {}) {
                 fatal: 'uncaughtException',
             });
         }
-    });
-    process.on('unhandledRejection', reason => {
+    };
+    const unhandledRejectionHandler = (reason) => {
         onError?.(reason, 'unhandledRejection');
         if (exitOnFatal) {
             close(fatalExitCode, {
@@ -44,21 +55,34 @@ export function installExitHandlers(options = {}) {
                 fatal: 'unhandledRejection',
             });
         }
-    });
-    ['SIGINT', 'SIGTERM', 'SIGQUIT'].forEach(signal => {
-        process.on(signal, () => {
+    };
+    const signalHandlers = ['SIGINT', 'SIGTERM', 'SIGQUIT'].map(signal => {
+        const handler = () => {
             close(SIGNAL_EXIT_CODES()[signal], { kind: 'signal', signal });
             if (exitOnSignal) {
-                // eslint-disable-next-line n/no-process-exit
+                // eslint-disable-next-line unicorn/no-process-exit,n/no-process-exit
                 process.exit(SIGNAL_EXIT_CODES()[signal]);
             }
-        });
+        };
+        process.on(signal, handler);
+        return { signal, handler };
     });
-    process.on('exit', code => {
+    const exitHandler = (code) => {
         if (closedReason) {
             return;
         }
         close(code, { kind: 'exit' });
-    });
+    };
+    process.on('uncaughtException', uncaughtExceptionHandler);
+    process.on('unhandledRejection', unhandledRejectionHandler);
+    process.on('exit', exitHandler);
+    return () => {
+        process.removeListener('uncaughtException', uncaughtExceptionHandler);
+        process.removeListener('unhandledRejection', unhandledRejectionHandler);
+        process.removeListener('exit', exitHandler);
+        signalHandlers.forEach(({ signal, handler }) => {
+            process.removeListener(signal, handler);
+        });
+    };
 }
 //# sourceMappingURL=exit-process.js.map

package/src/lib/exit-process.js.map

@@ -1 +1 @@
-{"version":3,"file":"exit-process.js","sourceRoot":"","sources":["../../../src/lib/exit-process.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,OAAO,MAAM,cAAc,CAAC;AAEnC,6DAA6D;AAC7D,uOAAuO;AACvO,MAAM,4BAA4B,GAAG,GAAG,CAAC;AACzC,MAAM,kBAAkB,GAAG,CAAC,YAAoB,EAAE,EAAE,CAClD,4BAA4B,GAAG,YAAY,CAAC;AAE9C,MAAM,WAAW,GAAG,CAAC,CAAC;AACtB,MAAM,YAAY,GAAG,EAAE,CAAC;AACxB,MAAM,YAAY,GAAG,CAAC,CAAC;AAEvB,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAA+B,EAAE;IAChE,MAAM,gBAAgB,GAAG,EAAE,CAAC,QAAQ,EAAE,KAAK,OAAO,CAAC;IACnD,OAAO;QACL,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,kBAAkB,CAAC,WAAW,CAAC;QACxE,OAAO,EAAE,kBAAkB,CAAC,YAAY,CAAC;QACzC,OAAO,EAAE,kBAAkB,CAAC,YAAY,CAAC;KAC1C,CAAC;AACJ,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AAkBzC,MAAM,UAAU,mBAAmB,CAAC,UAA8B,EAAE;IAClE,6CAA6C;IAC7C,IAAI,YAAqC,CAAC;IAC1C,MAAM,EACJ,MAAM,EACN,OAAO,EACP,WAAW,EACX,YAAY,EACZ,aAAa,GAAG,uBAAuB,GACxC,GAAG,OAAO,CAAC;IAEZ,MAAM,KAAK,GAAG,CAAC,IAAY,EAAE,MAAmB,EAAE,EAAE;QAClD,IAAI,YAAY,EAAE,CAAC;YACjB,OAAO;QACT,CAAC;QACD,YAAY,GAAG,MAAM,CAAC;QACtB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACzB,CAAC,CAAC;IAEF,OAAO,CAAC,EAAE,CAAC,mBAAmB,EAAE,GAAG,CAAC,EAAE;QACpC,OAAO,EAAE,CAAC,GAAG,EAAE,mBAAmB,CAAC,CAAC;QACpC,IAAI,WAAW,EAAE,CAAC;YAChB,KAAK,CAAC,aAAa,EAAE;gBACnB,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,mBAAmB;aAC3B,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,EAAE,CAAC,oBAAoB,EAAE,MAAM,CAAC,EAAE;QACxC,OAAO,EAAE,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;QACxC,IAAI,WAAW,EAAE,CAAC;YAChB,KAAK,CAAC,aAAa,EAAE;gBACnB,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,oBAAoB;aAC5B,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC,CAAC;IAEF,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,CAAW,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE;QAC3D,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE;YACtB,KAAK,CAAC,iBAAiB,EAAE,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;YAC/D,IAAI,YAAY,EAAE,CAAC;gBACjB,6CAA6C;gBAC7C,OAAO,CAAC,IAAI,CAAC,iBAAiB,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;YAC5C,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE;QACxB,IAAI,YAAY,EAAE,CAAC;YACjB,OAAO;QACT,CAAC;QACD,KAAK,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAChC,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"exit-process.js","sourceRoot":"","sources":["../../../src/lib/exit-process.ts"],"names":[],"mappings":"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"}

package/src/lib/performance-observer.d.ts

@@ -1,18 +1,199 @@
 import { type PerformanceEntry } from 'node:perf_hooks';
 import type { AppendableSink } from './wal.js';
+/**
+ * Encoder that converts PerformanceEntry to domain events.
+ *
+ * Pure function that transforms performance entries into domain events.
+ * Should be stateless, synchronous, and have no side effects.
+ * Returns a readonly array of encoded items.
+ */
+export type PerformanceEntryEncoder<F> = (entry: PerformanceEntry) => readonly F[];
+/**
+ * Default threshold for triggering queue flushes based on queue length.
+ * When the queue length reaches (maxQueueSize - flushThreshold),
+ * a flush is triggered to prevent overflow. This provides a buffer zone
+ * before hitting the maximum queue capacity.
+ */
 export declare const DEFAULT_FLUSH_THRESHOLD = 20;
+/**
+ * Default maximum number of items allowed in the queue before entries are dropped.
+ * This acts as a memory safety limit to prevent unbounded memory growth
+ * in case of sink slowdown or high-frequency performance entries.
+ */
+export declare const DEFAULT_MAX_QUEUE_SIZE = 10000;
+/**
+ * Validates the flush threshold configuration to ensure sensible bounds.
+ *
+ * The flush threshold must be positive and cannot exceed the maximum queue size,
+ * as it represents a buffer zone within the queue capacity.
+ *
+ * @param flushThreshold - The threshold value to validate (must be > 0)
+ * @param maxQueueSize - The maximum queue size for comparison (flushThreshold <= maxQueueSize)
+ * @throws {Error} If flushThreshold is not positive or exceeds maxQueueSize
+ */
+export declare function validateFlushThreshold(flushThreshold: number, maxQueueSize: number): void;
+/**
+ * Configuration options for the PerformanceObserverSink.
+ *
+ * @template T - The type of encoded performance data that will be written to the sink
+ */
 export type PerformanceObserverOptions<T> = {
+    /**
+     * The sink where encoded performance entries will be written.
+     * Must implement the AppendableSink interface for handling the encoded data.
+     */
     sink: AppendableSink<T>;
-    encode: (entry: PerformanceEntry) => T[];
-    buffered?: boolean;
+    /**
+     * Function that encodes raw PerformanceEntry objects into domain-specific types.
+     * This transformer converts Node.js performance entries into application-specific data structures.
+     * Returns a readonly array of encoded items.
+     */
+    encodePerfEntry: PerformanceEntryEncoder<T>;
+    /**
+     * Whether to enable buffered observation mode.
+     * When true, captures all performance entries that occurred before observation started.
+     * When false, only captures entries after subscription begins.
+     *
+     * @default true
+     */
+    captureBufferedEntries?: boolean;
+    /**
+     * Threshold for triggering queue flushes.
+     * Flushes occur in two scenarios:
+     * 1. When queue length reaches (maxQueueSize - flushThreshold)
+     * 2. When the number of items added since last flush reaches flushThreshold
+     * Larger values provide more buffer space before hitting capacity limits.
+     *
+     * @default DEFAULT_FLUSH_THRESHOLD (20)
+     */
     flushThreshold?: number;
+    /**
+     * Maximum number of items allowed in the queue before new entries are dropped.
+     * Acts as a memory safety limit to prevent unbounded growth during sink slowdown.
+     *
+     * @default DEFAULT_MAX_QUEUE_SIZE (10000)
+     */
+    maxQueueSize?: number;
+    /**
+     * Name of the environment variable to check for debug mode.
+     * When the env var is set to 'true', encode failures create performance marks for debugging.
+     *
+     * @default 'CP_PROFILER_DEBUG'
+     */
+    debugEnvVar?: string;
 };
+/**
+ * A sink implementation that observes Node.js performance entries and forwards them to a configurable sink.
+ *
+ * This class provides a buffered, memory-safe bridge between Node.js PerformanceObserver
+ * and application-specific data sinks. It handles performance entry encoding, queue management,
+ * and graceful degradation under high load conditions.
+ *
+ * Performance entries flow through the following lifecycle:
+ *
+ * - Queued in Memory 💾
+ *   - Items stored in queue (`#queue`) until flushed
+ *   - Queue limited by `maxQueueSize` to prevent unbounded growth
+ *   - Items remain in queue if sink is closed during flush
+ *
+ * - Successfully Written 📤
+ *   - Items written to sink and counted in `getStats().written`
+ *   - Queue cleared after successful batch writes
+ *
+ * - Item Disposition Scenarios 💥
+ *   - **Encode Failure**: ❌ Items lost when `encode()` throws. Creates perf mark if debug env var (specified by `debugEnvVar`) is set to 'true'.
+ *   - **Sink Write Failure**: 💾 Items stay in queue when sink write fails during flush
+ *   - **Sink Closed**: 💾 Items stay in queue when sink is closed during flush
+ *   - **Proactive Flush Throws**: 💾 Items stay in queue when `flush()` throws during threshold check
+ *   - **Final Flush Throws**: 💾 Items stay in queue when `flush()` throws at end of callback
+ *   - **Buffered Flush Throws**: 💾 Items stay in queue when buffered entries flush fails
+ *   - **Queue Overflow**: ❌ Items dropped when queue reaches `maxQueueSize`
+ *
+ * @template T - The type of encoded performance data written to the sink
+ * @implements {Observer} - Lifecycle management interface
+ * @implements {Buffered} - Queue statistics interface
+ */
 export declare class PerformanceObserverSink<T> {
     #private;
+    /**
+     * Creates a new PerformanceObserverSink with the specified configuration.
+     *
+     * @param options - Configuration options for the performance observer sink
+     * @throws {Error} If flushThreshold validation fails (must be > 0 and <= maxQueueSize)
+     */
     constructor(options: PerformanceObserverOptions<T>);
-    encode(entry: PerformanceEntry): T[];
+    /**
+     * Returns whether debug mode is enabled for encode failures.
+     *
+     * Debug mode is determined by the environment variable specified by `debugEnvVar`
+     * (defaults to 'CP_PROFILER_DEBUG'). When enabled, encode failures create
+     * performance marks for debugging.
+     *
+     * @returns true if debug mode is enabled, false otherwise
+     */
+    get debug(): boolean;
+    /**
+     * Returns current queue statistics for monitoring and debugging.
+     *
+     * Provides insight into the current state of the performance entry queue,
+     * useful for monitoring memory usage and processing throughput.
+     *
+     * @returns Object containing all states and entry counts
+     */
+    getStats(): {
+        isSubscribed: boolean;
+        queued: number;
+        dropped: number;
+        written: number;
+        maxQueueSize: number;
+        flushThreshold: number;
+        addedSinceLastFlush: number;
+        buffered: boolean;
+    };
+    /**
+     * Encodes a raw PerformanceEntry using the configured encoder function.
+     *
+     * This method delegates to the user-provided encoder function, allowing
+     * transformation of Node.js performance entries into application-specific types.
+     *
+     * @param entry - The raw performance entry to encode
+     * @returns Readonly array of encoded items
+     */
+    encode(entry: PerformanceEntry): readonly T[];
+    /**
+     * Starts observing performance entries and forwarding them to the sink.
+     *
+     * Creates a Node.js PerformanceObserver that monitors 'mark' and 'measure' entries.
+     * The observer uses a bounded queue with proactive flushing to manage memory usage.
+     * When buffered mode is enabled, any existing buffered entries are immediately flushed.
+     * If the sink is closed, items stay in the queue until reopened.
+     *
+     */
     subscribe(): void;
+    /**
+     * Flushes all queued performance entries to the sink.
+     *
+     * Writes all currently queued encoded performance entries to the configured sink.
+     * If the sink is closed, flush is a no-op and items stay in the queue until reopened.
+     * The queue is always cleared after flush attempt, regardless of success or failure.
+     */
     flush(): void;
+    /**
+     * Stops observing performance entries and cleans up resources.
+     *
+     * Performs a final flush of any remaining queued entries, then disconnects
+     * the PerformanceObserver and releases all references.
+     *
+     * This method is idempotent - safe to call multiple times.
+     */
     unsubscribe(): void;
+    /**
+     * Checks whether the performance observer is currently active.
+     *
+     * Returns true if the sink is subscribed and actively observing performance entries.
+     * This indicates that a PerformanceObserver instance exists and is connected.
+     *
+     * @returns true if currently subscribed and observing, false otherwise
+     */
     isSubscribed(): boolean;
 }

package/src/lib/performance-observer.js

@@ -1,35 +1,216 @@
 import { PerformanceObserver, performance, } from 'node:perf_hooks';
+import { isEnvVarEnabled } from './env.js';
+import { PROFILER_DEBUG_ENV_VAR } from './profiler/constants.js';
+/**
+ * Array of performance entry types that this observer monitors.
+ * Only 'mark' and 'measure' entries are tracked as they represent
+ * user-defined performance markers and measurements.
+ */
 const OBSERVED_TYPES = ['mark', 'measure'];
+const OBSERVED_TYPE_SET = new Set(OBSERVED_TYPES);
+/**
+ * Converts an error to a performance mark name for debugging.
+ * @param error - The error that occurred
+ * @param entry - The performance entry that failed to encode
+ * @returns A mark name string
+ */
+function errorToPerfMark(error, entry) {
+    const errorName = error instanceof Error ? error.name : 'UnknownError';
+    const entryName = entry.name || 'unnamed';
+    return `encode-error:${errorName}:${entryName}`;
+}
+/**
+ * Default threshold for triggering queue flushes based on queue length.
+ * When the queue length reaches (maxQueueSize - flushThreshold),
+ * a flush is triggered to prevent overflow. This provides a buffer zone
+ * before hitting the maximum queue capacity.
+ */
 export const DEFAULT_FLUSH_THRESHOLD = 20;
+/**
+ * Default maximum number of items allowed in the queue before entries are dropped.
+ * This acts as a memory safety limit to prevent unbounded memory growth
+ * in case of sink slowdown or high-frequency performance entries.
+ */
+export const DEFAULT_MAX_QUEUE_SIZE = 10_000;
+/**
+ * Validates the flush threshold configuration to ensure sensible bounds.
+ *
+ * The flush threshold must be positive and cannot exceed the maximum queue size,
+ * as it represents a buffer zone within the queue capacity.
+ *
+ * @param flushThreshold - The threshold value to validate (must be > 0)
+ * @param maxQueueSize - The maximum queue size for comparison (flushThreshold <= maxQueueSize)
+ * @throws {Error} If flushThreshold is not positive or exceeds maxQueueSize
+ */
+export function validateFlushThreshold(flushThreshold, maxQueueSize) {
+    if (flushThreshold <= 0) {
+        throw new Error('flushThreshold must be > 0');
+    }
+    if (flushThreshold > maxQueueSize) {
+        throw new Error('flushThreshold must be <= maxQueueSize');
+    }
+}
+/**
+ * A sink implementation that observes Node.js performance entries and forwards them to a configurable sink.
+ *
+ * This class provides a buffered, memory-safe bridge between Node.js PerformanceObserver
+ * and application-specific data sinks. It handles performance entry encoding, queue management,
+ * and graceful degradation under high load conditions.
+ *
+ * Performance entries flow through the following lifecycle:
+ *
+ * - Queued in Memory 💾
+ *   - Items stored in queue (`#queue`) until flushed
+ *   - Queue limited by `maxQueueSize` to prevent unbounded growth
+ *   - Items remain in queue if sink is closed during flush
+ *
+ * - Successfully Written 📤
+ *   - Items written to sink and counted in `getStats().written`
+ *   - Queue cleared after successful batch writes
+ *
+ * - Item Disposition Scenarios 💥
+ *   - **Encode Failure**: ❌ Items lost when `encode()` throws. Creates perf mark if debug env var (specified by `debugEnvVar`) is set to 'true'.
+ *   - **Sink Write Failure**: 💾 Items stay in queue when sink write fails during flush
+ *   - **Sink Closed**: 💾 Items stay in queue when sink is closed during flush
+ *   - **Proactive Flush Throws**: 💾 Items stay in queue when `flush()` throws during threshold check
+ *   - **Final Flush Throws**: 💾 Items stay in queue when `flush()` throws at end of callback
+ *   - **Buffered Flush Throws**: 💾 Items stay in queue when buffered entries flush fails
+ *   - **Queue Overflow**: ❌ Items dropped when queue reaches `maxQueueSize`
+ *
+ * @template T - The type of encoded performance data written to the sink
+ * @implements {Observer} - Lifecycle management interface
+ * @implements {Buffered} - Queue statistics interface
+ */
 export class PerformanceObserverSink {
-    #encode;
+    /** Encoder function for transforming PerformanceEntry objects into domain types */
+    #encodePerfEntry;
+    /** Whether buffered observation mode is enabled */
     #buffered;
+    /** Threshold for triggering flushes based on queue length proximity to max capacity */
     #flushThreshold;
+    /** Maximum number of items allowed in queue before dropping new entries (hard memory limit) */
+    #maxQueueSize;
+    /** The target sink where encoded performance data is written */
     #sink;
+    /** Node.js PerformanceObserver instance, undefined when not subscribed */
     #observer;
-    #pendingCount = 0;
-    // "cursor" per type: how many we already wrote from the global buffer
-    #written;
+    /** Bounded queue storing encoded performance items awaiting flush */
+    #queue = [];
+    /** Count of performance entries dropped due to queue overflow */
+    #dropped = 0;
+    /** Count of performance entries successfully written to sink */
+    #written = 0;
+    /** Number of items added to queue since last successful flush */
+    #addedSinceLastFlush = 0;
+    /** Whether debug mode is enabled for encode failures */
+    #debug;
+    /**
+     * Creates a new PerformanceObserverSink with the specified configuration.
+     *
+     * @param options - Configuration options for the performance observer sink
+     * @throws {Error} If flushThreshold validation fails (must be > 0 and <= maxQueueSize)
+     */
     constructor(options) {
-        const { encode, sink, buffered, flushThreshold } = options;
-        this.#encode = encode;
-        this.#written = new Map(OBSERVED_TYPES.map(t => [t, 0]));
+        const { encodePerfEntry, sink, captureBufferedEntries, flushThreshold = DEFAULT_FLUSH_THRESHOLD, maxQueueSize = DEFAULT_MAX_QUEUE_SIZE, debugEnvVar = PROFILER_DEBUG_ENV_VAR, } = options;
+        this.#encodePerfEntry = encodePerfEntry;
         this.#sink = sink;
-        this.#buffered = buffered ?? false;
-        this.#flushThreshold = flushThreshold ?? DEFAULT_FLUSH_THRESHOLD;
+        this.#buffered = captureBufferedEntries ?? true;
+        this.#maxQueueSize = maxQueueSize;
+        validateFlushThreshold(flushThreshold, this.#maxQueueSize);
+        this.#flushThreshold = flushThreshold;
+        this.#debug = isEnvVarEnabled(debugEnvVar);
+    }
+    /**
+     * Returns whether debug mode is enabled for encode failures.
+     *
+     * Debug mode is determined by the environment variable specified by `debugEnvVar`
+     * (defaults to 'CP_PROFILER_DEBUG'). When enabled, encode failures create
+     * performance marks for debugging.
+     *
+     * @returns true if debug mode is enabled, false otherwise
+     */
+    get debug() {
+        return this.#debug;
     }
+    /**
+     * Returns current queue statistics for monitoring and debugging.
+     *
+     * Provides insight into the current state of the performance entry queue,
+     * useful for monitoring memory usage and processing throughput.
+     *
+     * @returns Object containing all states and entry counts
+     */
+    getStats() {
+        return {
+            isSubscribed: this.isSubscribed(),
+            queued: this.#queue.length,
+            dropped: this.#dropped,
+            written: this.#written,
+            maxQueueSize: this.#maxQueueSize,
+            flushThreshold: this.#flushThreshold,
+            addedSinceLastFlush: this.#addedSinceLastFlush,
+            buffered: this.#buffered,
+        };
+    }
+    /**
+     * Encodes a raw PerformanceEntry using the configured encoder function.
+     *
+     * This method delegates to the user-provided encoder function, allowing
+     * transformation of Node.js performance entries into application-specific types.
+     *
+     * @param entry - The raw performance entry to encode
+     * @returns Readonly array of encoded items
+     */
     encode(entry) {
-        return this.#encode(entry);
+        return this.#encodePerfEntry(entry);
     }
+    /**
+     * Starts observing performance entries and forwarding them to the sink.
+     *
+     * Creates a Node.js PerformanceObserver that monitors 'mark' and 'measure' entries.
+     * The observer uses a bounded queue with proactive flushing to manage memory usage.
+     * When buffered mode is enabled, any existing buffered entries are immediately flushed.
+     * If the sink is closed, items stay in the queue until reopened.
+     *
+     */
     subscribe() {
         if (this.#observer) {
             return;
         }
-        // Only used to trigger the flush - it's not processing the entries, just counting them
-        this.#observer = new PerformanceObserver((list) => {
-            const batchCount = OBSERVED_TYPES.reduce((n, t) => n + list.getEntriesByType(t).length, 0);
-            this.#pendingCount += batchCount;
-            if (this.#pendingCount >= this.#flushThreshold) {
+        this.#observer = new PerformanceObserver(list => {
+            list.getEntries().forEach(entry => {
+                if (OBSERVED_TYPE_SET.has(entry.entryType)) {
+                    try {
+                        const items = this.encode(entry);
+                        items.forEach(item => {
+                            // ❌ MAX QUEUE OVERFLOW
+                            if (this.#queue.length >= this.#maxQueueSize) {
+                                this.#dropped++; // Items are lost forever
+                                return;
+                            }
+                            if (this.#queue.length >=
+                                this.#maxQueueSize - this.#flushThreshold) {
+                                this.flush();
+                            }
+                            this.#queue.push(item);
+                            this.#addedSinceLastFlush++;
+                        });
+                    }
+                    catch (error) {
+                        // ❌ Encode failure: item lost forever as user has to fix encode function.
+                        this.#dropped++;
+                        if (this.#debug) {
+                            try {
+                                performance.mark(errorToPerfMark(error, entry));
+                            }
+                            catch {
+                                // Ignore mark failures to prevent double errors
+                            }
+                        }
+                    }
+                }
+            });
+            if (this.#addedSinceLastFlush >= this.#flushThreshold) {
                 this.flush();
             }
         });
@@ -37,33 +218,65 @@ export class PerformanceObserverSink {
             entryTypes: OBSERVED_TYPES,
             buffered: this.#buffered,
         });
+        if (this.#buffered) {
+            this.flush();
+        }
     }
+    /**
+     * Flushes all queued performance entries to the sink.
+     *
+     * Writes all currently queued encoded performance entries to the configured sink.
+     * If the sink is closed, flush is a no-op and items stay in the queue until reopened.
+     * The queue is always cleared after flush attempt, regardless of success or failure.
+     */
     flush() {
-        if (!this.#observer) {
+        if (this.#queue.length === 0) {
+            return;
+        }
+        if (this.#sink.isClosed()) {
             return;
         }
-        OBSERVED_TYPES.forEach(t => {
-            const written = this.#written.get(t) ?? 0;
-            const fresh = performance.getEntriesByType(t).slice(written);
+        // Process each item in queue
+        const failedItems = [];
+        this.#queue.forEach(item => {
             try {
-                fresh
-                    .flatMap(entry => this.encode(entry))
-                    .forEach(item => this.#sink.append(item));
-                this.#written.set(t, written + fresh.length);
+                this.#sink.append(item);
+                this.#written++;
             }
-            catch (error) {
-                throw new Error('PerformanceObserverSink failed to write items to sink.', { cause: error });
+            catch {
+                failedItems.push(item);
             }
         });
-        this.#pendingCount = 0;
+        // Clear queue but keep failed items for retry
+        this.#queue.length = 0;
+        this.#queue.push(...failedItems);
+        this.#addedSinceLastFlush = failedItems.length;
     }
+    /**
+     * Stops observing performance entries and cleans up resources.
+     *
+     * Performs a final flush of any remaining queued entries, then disconnects
+     * the PerformanceObserver and releases all references.
+     *
+     * This method is idempotent - safe to call multiple times.
+     */
     unsubscribe() {
         if (!this.#observer) {
             return;
         }
-        this.#observer?.disconnect();
+        this.flush();
+        this.#addedSinceLastFlush = 0;
+        this.#observer.disconnect();
         this.#observer = undefined;
     }
+    /**
+     * Checks whether the performance observer is currently active.
+     *
+     * Returns true if the sink is subscribed and actively observing performance entries.
+     * This indicates that a PerformanceObserver instance exists and is connected.
+     *
+     * @returns true if currently subscribed and observing, false otherwise
+     */
     isSubscribed() {
         return this.#observer !== undefined;
     }