@code-pushup/utils 0.110.0 → 0.111.1

package/src/lib/performance-observer.js.map

@@ -1 +1 @@
-{"version":3,"file":"performance-observer.js","sourceRoot":"","sources":["../../../src/lib/performance-observer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"performance-observer.js","sourceRoot":"","sources":["../../../src/lib/performance-observer.ts"],"names":[],"mappings":"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"}

package/src/lib/profiler/constants.d.ts

@@ -1,6 +1,24 @@
+/**
+ * Environment variable name for enabling/disabling profiling globally.
+ * When set to 'true', profiling is enabled. When set to 'false' or unset, profiling is disabled.
+ *
+ * @example
+ * CP_PROFILING=true npm run dev
+ */
 export declare const PROFILER_ENABLED_ENV_VAR = "CP_PROFILING";
-export declare const PROFILER_COORDINATOR_FLAG_ENV_VAR = "CP_PROFILER_COORDINATOR";
-export declare const PROFILER_ORIGIN_PID_ENV_VAR = "CP_PROFILER_ORIGIN_PID";
-export declare const PROFILER_DIRECTORY_ENV_VAR = "CP_PROFILER_DIR";
-export declare const PROFILER_BASE_NAME = "trace";
-export declare const PROFILER_DIRECTORY = "./tmp/profiles";
+/**
+ * Environment variable name for enabling debug mode for profiler state transitions.
+ * When set to 'true', profiler state transitions create performance marks for debugging.
+ *
+ * @example
+ * CP_PROFILER_DEBUG=true npm run dev
+ */
+export declare const PROFILER_DEBUG_ENV_VAR = "CP_PROFILER_DEBUG";
+/**
+ * Environment variable name for setting the Sharded WAL Coordinator ID.
+ * This ID is used to identify the coordinator instance in a sharded Write-Ahead Logging setup.
+ *
+ * @example
+ * CP_SHARDED_WAL_COORDINATOR_ID=coordinator-1 npm run dev
+ */
+export declare const SHARDED_WAL_COORDINATOR_ID_ENV_VAR = "CP_SHARDED_WAL_COORDINATOR_ID";

package/src/lib/profiler/constants.js

@@ -1,7 +1,25 @@
+/**
+ * Environment variable name for enabling/disabling profiling globally.
+ * When set to 'true', profiling is enabled. When set to 'false' or unset, profiling is disabled.
+ *
+ * @example
+ * CP_PROFILING=true npm run dev
+ */
 export const PROFILER_ENABLED_ENV_VAR = 'CP_PROFILING';
-export const PROFILER_COORDINATOR_FLAG_ENV_VAR = 'CP_PROFILER_COORDINATOR';
-export const PROFILER_ORIGIN_PID_ENV_VAR = 'CP_PROFILER_ORIGIN_PID';
-export const PROFILER_DIRECTORY_ENV_VAR = 'CP_PROFILER_DIR';
-export const PROFILER_BASE_NAME = 'trace';
-export const PROFILER_DIRECTORY = './tmp/profiles';
+/**
+ * Environment variable name for enabling debug mode for profiler state transitions.
+ * When set to 'true', profiler state transitions create performance marks for debugging.
+ *
+ * @example
+ * CP_PROFILER_DEBUG=true npm run dev
+ */
+export const PROFILER_DEBUG_ENV_VAR = 'CP_PROFILER_DEBUG';
+/**
+ * Environment variable name for setting the Sharded WAL Coordinator ID.
+ * This ID is used to identify the coordinator instance in a sharded Write-Ahead Logging setup.
+ *
+ * @example
+ * CP_SHARDED_WAL_COORDINATOR_ID=coordinator-1 npm run dev
+ */
+export const SHARDED_WAL_COORDINATOR_ID_ENV_VAR = 'CP_SHARDED_WAL_COORDINATOR_ID';
 //# sourceMappingURL=constants.js.map

package/src/lib/profiler/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../src/lib/profiler/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,wBAAwB,GAAG,cAAc,CAAC;AACvD,MAAM,CAAC,MAAM,iCAAiC,GAAG,yBAAyB,CAAC;AAC3E,MAAM,CAAC,MAAM,2BAA2B,GAAG,wBAAwB,CAAC;AACpE,MAAM,CAAC,MAAM,0BAA0B,GAAG,iBAAiB,CAAC;AAC5D,MAAM,CAAC,MAAM,kBAAkB,GAAG,OAAO,CAAC;AAC1C,MAAM,CAAC,MAAM,kBAAkB,GAAG,gBAAgB,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../src/lib/profiler/constants.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,cAAc,CAAC;AAEvD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,mBAAmB,CAAC;AAE1D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAC7C,+BAA+B,CAAC"}

package/src/lib/profiler/profiler-node.d.ts

@@ -0,0 +1,101 @@
+import { type PerformanceObserverOptions } from '../performance-observer.js';
+import type { ActionTrackEntryPayload } from '../user-timing-extensibility-api.type.js';
+import { Profiler, type ProfilerOptions } from './profiler.js';
+/**
+ * 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 extends string | object, Tracks extends Record<string, ActionTrackEntryPayload>> = ProfilerOptions<Tracks> & Omit<PerformanceObserverOptions<DomainEvents>, 'sink'> & {
+    /**
+     * File path for the WriteAheadLogFile sink.
+     * If not provided, defaults to `trace.json` in the current working directory.
+     *
+     * @default path.join(process.cwd(), 'trace.json')
+     */
+    filename?: string;
+    /**
+     * Name of the environment variable to check for debug mode.
+     * When the env var is set to 'true', profiler state transitions create performance marks for debugging.
+     *
+     * @default 'CP_PROFILER_DEBUG'
+     */
+    debugEnvVar?: string;
+};
+/**
+ * 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 automatically creates a {@link WriteAheadLogFile} sink that buffers
+ * performance entries and ensures they are written out during process termination, even for unexpected exits.
+ *
+ * The sink uses a default codec for serializing performance data to JSON format,
+ * enabling compatibility with Chrome DevTools trace file format.
+ *
+ * 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).
+ *
+ * @template DomainEvents - The type of domain-specific events encoded by the performance observer sink
+ * @template Tracks - Record type defining available track names and their configurations
+ */
+export declare class NodejsProfiler<DomainEvents extends string | object, Tracks extends Record<string, ActionTrackEntryPayload> = Record<string, ActionTrackEntryPayload>> extends Profiler<Tracks> {
+    #private;
+    /**
+     * Creates a NodejsProfiler instance.
+     * A WriteAheadLogFile sink is automatically created for buffering performance data.
+     * @param options - Configuration options
+     */
+    constructor(options: NodejsProfilerOptions<DomainEvents, Tracks>);
+    /**
+     * Returns whether debug mode is enabled for profiler state transitions.
+     *
+     * Debug mode is initially determined by the environment variable specified by `debugEnvVar`
+     * (defaults to 'CP_PROFILER_DEBUG') during construction, but can be changed at runtime
+     * using {@link setDebugMode}. When enabled, profiler state transitions create
+     * performance marks for debugging.
+     *
+     * @returns true if debug mode is enabled, false otherwise
+     */
+    get debug(): boolean;
+    /**
+     * Sets debug mode for profiler state transitions.
+     *
+     * When debug mode is enabled, profiler state transitions create performance marks
+     * for debugging. This allows runtime control of debug mode without needing to
+     * restart the application or change environment variables.
+     *
+     * @param enabled - Whether to enable debug mode
+     */
+    setDebugMode(enabled: boolean): void;
+    /**
+     * Closes profiler and releases resources. Idempotent, safe for exit handlers.
+     * **Exit Handler Usage**: Call only this method from process exit handlers.
+     */
+    close(): void;
+    /** @returns Current profiler state */
+    get state(): 'idle' | 'running' | 'closed';
+    /** @returns Whether profiler is in 'running' state */
+    isEnabled(): boolean;
+    /** Enables profiling (start/stop) */
+    setEnabled(enabled: boolean): void;
+    /** @returns Queue statistics and profiling state for monitoring */
+    get stats(): {
+        debug: boolean;
+        state: "idle" | "running" | "closed";
+        walOpen: boolean;
+        isSubscribed: boolean;
+        queued: number;
+        dropped: number;
+        written: number;
+        maxQueueSize: number;
+        flushThreshold: number;
+        addedSinceLastFlush: number;
+        buffered: boolean;
+    };
+    /** Flushes buffered performance data to sink. */
+    flush(): void;
+    /** @returns The file path of the WriteAheadLogFile sink */
+    get filePath(): string;
+}

package/src/lib/profiler/profiler-node.js

@@ -0,0 +1,217 @@
+import path from 'node:path';
+import { isEnvVarEnabled } from '../env.js';
+import { subscribeProcessExit } from '../exit-process.js';
+import { PerformanceObserverSink, } from '../performance-observer.js';
+import { objectToEntries } from '../transform.js';
+import { errorToMarkerPayload } from '../user-timing-extensibility-api-utils.js';
+import { WriteAheadLogFile, getShardId, getShardedGroupId, getShardedPath, } from '../wal.js';
+import { PROFILER_DEBUG_ENV_VAR, PROFILER_ENABLED_ENV_VAR, } from './constants.js';
+import { Profiler } from './profiler.js';
+import { traceEventWalFormat } from './wal-json-trace.js';
+/**
+ * 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 automatically creates a {@link WriteAheadLogFile} sink that buffers
+ * performance entries and ensures they are written out during process termination, even for unexpected exits.
+ *
+ * The sink uses a default codec for serializing performance data to JSON format,
+ * enabling compatibility with Chrome DevTools trace file format.
+ *
+ * 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).
+ *
+ * @template DomainEvents - The type of domain-specific events encoded by the performance observer sink
+ * @template Tracks - Record type defining available track names and their configurations
+ */
+export class NodejsProfiler extends Profiler {
+    #sink;
+    #performanceObserverSink;
+    #state = 'idle';
+    #debug;
+    #unsubscribeExitHandlers;
+    /**
+     * Creates a NodejsProfiler instance.
+     * A WriteAheadLogFile sink is automatically created for buffering performance data.
+     * @param options - Configuration options
+     */
+    // eslint-disable-next-line max-lines-per-function
+    constructor(options) {
+        const { encodePerfEntry, captureBufferedEntries, flushThreshold, maxQueueSize, enabled, filename, debugEnvVar = PROFILER_DEBUG_ENV_VAR, ...profilerOptions } = options;
+        const initialEnabled = enabled ?? isEnvVarEnabled(PROFILER_ENABLED_ENV_VAR);
+        super({ ...profilerOptions, enabled: initialEnabled });
+        const walFormat = traceEventWalFormat();
+        this.#sink = new WriteAheadLogFile({
+            file: filename ??
+                path.join(process.cwd(), getShardedPath({
+                    dir: 'tmp/profiles',
+                    groupId: getShardedGroupId(),
+                    shardId: getShardId(),
+                    format: walFormat,
+                })),
+            codec: walFormat.codec,
+        });
+        this.#debug = isEnvVarEnabled(debugEnvVar);
+        this.#performanceObserverSink = new PerformanceObserverSink({
+            sink: this.#sink,
+            encodePerfEntry,
+            captureBufferedEntries,
+            flushThreshold,
+            maxQueueSize,
+            debugEnvVar,
+        });
+        this.#unsubscribeExitHandlers = subscribeProcessExit({
+            onError: (error, kind) => {
+                this.#handleFatalError(error, kind);
+            },
+            onExit: (_code) => {
+                this.close();
+            },
+        });
+        if (initialEnabled) {
+            this.#transition('running');
+        }
+    }
+    /**
+     * Returns whether debug mode is enabled for profiler state transitions.
+     *
+     * Debug mode is initially determined by the environment variable specified by `debugEnvVar`
+     * (defaults to 'CP_PROFILER_DEBUG') during construction, but can be changed at runtime
+     * using {@link setDebugMode}. When enabled, profiler state transitions create
+     * performance marks for debugging.
+     *
+     * @returns true if debug mode is enabled, false otherwise
+     */
+    get debug() {
+        return this.#debug;
+    }
+    /**
+     * Sets debug mode for profiler state transitions.
+     *
+     * When debug mode is enabled, profiler state transitions create performance marks
+     * for debugging. This allows runtime control of debug mode without needing to
+     * restart the application or change environment variables.
+     *
+     * @param enabled - Whether to enable debug mode
+     */
+    setDebugMode(enabled) {
+        this.#debug = enabled;
+    }
+    /**
+     * Creates a performance marker for a profiler state transition.
+     * @param transition - The state transition that occurred
+     */
+    #transitionMarker(transition) {
+        const transitionMarkerPayload = {
+            dataType: 'marker',
+            color: 'primary',
+            tooltipText: `Profiler state transition: ${transition}`,
+            properties: [['Transition', transition], ...objectToEntries(this.stats)],
+        };
+        this.marker(transition, transitionMarkerPayload);
+    }
+    /**
+     * Handles fatal errors by marking them and shutting down the profiler.
+     * @param error - The error that occurred
+     * @param kind - The kind of fatal error (uncaughtException or unhandledRejection)
+     */
+    #handleFatalError(error, kind) {
+        this.marker('Fatal Error', errorToMarkerPayload(error, {
+            tooltipText: `${kind} caused fatal error`,
+        }));
+        this.close(); // Ensures buffers flush and sink finalizes
+    }
+    /**
+     * Transitions the profiler to a new state, performing necessary setup/teardown operations.
+     *
+     * State transitions enforce lifecycle invariants:
+     * - `idle -> running`: Enables profiling, opens sink, and subscribes to performance observer
+     * - `running -> idle`: Disables profiling, unsubscribes, and closes sink (sink will be reopened on re-enable)
+     * - `running -> closed`: Disables profiling, unsubscribes, and closes sink (irreversible)
+     * - `idle -> closed`: Closes sink if it was opened (irreversible)
+     *
+     * @param next - The target state to transition to
+     * @throws {Error} If attempting to transition from 'closed' state or invalid transition
+     */
+    #transition(next) {
+        if (this.#state === next) {
+            return;
+        }
+        if (this.#state === 'closed') {
+            throw new Error('Profiler already closed');
+        }
+        const transition = `${this.#state}->${next}`;
+        switch (transition) {
+            case 'idle->running':
+                super.setEnabled(true);
+                this.#sink.open?.();
+                this.#performanceObserverSink.subscribe();
+                break;
+            case 'running->idle':
+            case 'running->closed':
+                super.setEnabled(false);
+                this.#performanceObserverSink.unsubscribe();
+                this.#sink.close?.();
+                break;
+            case 'idle->closed':
+                // Sink may have been opened before, close it
+                this.#sink.close?.();
+                break;
+            default:
+                throw new Error(`Invalid transition: ${this.#state} -> ${next}`);
+        }
+        this.#state = next;
+        if (this.#debug) {
+            this.#transitionMarker(transition);
+        }
+    }
+    /**
+     * Closes profiler and releases resources. Idempotent, safe for exit handlers.
+     * **Exit Handler Usage**: Call only this method from process exit handlers.
+     */
+    close() {
+        if (this.#state === 'closed') {
+            return;
+        }
+        this.#unsubscribeExitHandlers?.();
+        this.#transition('closed');
+    }
+    /** @returns Current profiler state */
+    get state() {
+        return this.#state;
+    }
+    /** @returns Whether profiler is in 'running' state */
+    isEnabled() {
+        return this.#state === 'running';
+    }
+    /** Enables profiling (start/stop) */
+    setEnabled(enabled) {
+        if (enabled) {
+            this.#transition('running');
+        }
+        else {
+            this.#transition('idle');
+        }
+    }
+    /** @returns Queue statistics and profiling state for monitoring */
+    get stats() {
+        return {
+            ...this.#performanceObserverSink.getStats(),
+            debug: this.#debug,
+            state: this.#state,
+            walOpen: !this.#sink.isClosed(),
+        };
+    }
+    /** Flushes buffered performance data to sink. */
+    flush() {
+        if (this.#state === 'closed') {
+            return; // No-op if closed
+        }
+        this.#performanceObserverSink.flush();
+    }
+    /** @returns The file path of the WriteAheadLogFile sink */
+    get filePath() {
+        return this.#sink.getPath();
+    }
+}
+//# sourceMappingURL=profiler-node.js.map

package/src/lib/profiler/profiler-node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiler-node.js","sourceRoot":"","sources":["../../../../src/lib/profiler/profiler-node.ts"],"names":[],"mappings":"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"}

package/src/lib/profiler/profiler.js

@@ -1,3 +1,4 @@
+import { performance } from 'node:perf_hooks';
 import process from 'node:process';
 import { threadId } from 'node:worker_threads';
 import { isEnvVarEnabled } from '../env.js';
@@ -20,7 +21,7 @@ export function getProfilerId() {
 export class Profiler {
     static instanceCount = 0;
     id = getProfilerId();
-    #enabled;
+    #enabled = false;
     #defaults;
     tracks;
     #ctxOf;
@@ -96,7 +97,7 @@ export class Profiler {
      * });
      */
     marker(name, opt) {
-        if (!this.#enabled) {
+        if (!this.isEnabled()) {
             return;
         }
         performance.mark(name, asOptions(markerPayload({
@@ -122,7 +123,7 @@ export class Profiler {
      *
      */
     measure(event, work, options) {
-        if (!this.#enabled) {
+        if (!this.isEnabled()) {
             return work();
         }
         const { start, success, error } = this.#ctxOf(event, options);
@@ -154,7 +155,7 @@ export class Profiler {
      *
      */
     async measureAsync(event, work, options) {
-        if (!this.#enabled) {
+        if (!this.isEnabled()) {
             return await work();
         }
         const { start, success, error } = this.#ctxOf(event, options);

package/src/lib/profiler/profiler.js.map

@@ -1 +1 @@
-{"version":3,"file":"profiler.js","sourceRoot":"","sources":["../../../../src/lib/profiler/profiler.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"profiler.js","sourceRoot":"","sources":["../../../../src/lib/profiler/profiler.ts"],"names":[],"mappings":"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"}

package/src/lib/wal.d.ts

@@ -16,8 +16,20 @@ export type InvalidEntry<O = string> = {
  * Interface for sinks that can append items.
  * Allows for different types of appendable storage (WAL, in-memory, etc.)
  */
-export type AppendableSink<T> = {
+export type AppendableSink<T> = Recoverable & {
     append: (item: T) => void;
+    isClosed: () => boolean;
+    open?: () => void;
+    close?: () => void;
+};
+/**
+ * Interface for sinks that support recovery operations.
+ * Represents the recoverable subset of AppendableSink functionality.
+ */
+export type Recoverable = {
+    recover: () => RecoverResult<unknown>;
+    repack: (out?: string) => void;
+    finalize?: (opt?: Record<string, unknown>) => void;
 };
 /**
  * Result of recovering records from a WAL file.
@@ -149,13 +161,13 @@ export declare function parseWalFormat<T extends object | string = object>(forma
  *
  * @returns true if this is the leader WAL process, false otherwise
  */
-export declare function isLeaderWal(envVarName: string, profilerID: string): boolean;
+export declare function isCoordinatorProcess(envVarName: string, profilerID: string): boolean;
 /**
  * Initialize the origin PID environment variable if not already set.
  * This must be done as early as possible before any user code runs.
  * Sets envVarName to the current process ID if not already defined.
  */
-export declare function setLeaderWal(envVarName: string, profilerID: string): void;
+export declare function setCoordinatorProcess(envVarName: string, profilerID: string): void;
 /**
  * Generates a human-readable shard ID.
  * This ID is unique per process/thread/shard combination and used in the file name.
@@ -214,15 +226,31 @@ export declare function getShardedFinalPath<T extends object | string = object>(
  */
 export declare class ShardedWal<T extends object | string = object> {
     #private;
+    static instanceCount: number;
     readonly groupId: string;
     /**
      * Create a sharded WAL manager.
+     *
+     * @param opt.dir - Base directory to store shard files (defaults to process.cwd())
+     * @param opt.format - WAL format configuration
+     * @param opt.groupId - Group ID for sharding (defaults to generated group ID)
+     * @param opt.coordinatorIdEnvVar - Environment variable name for storing coordinator ID (defaults to CP_SHARDED_WAL_COORDINATOR_ID)
      */
     constructor(opt: {
         dir?: string;
         format: Partial<WalFormat<T>>;
         groupId?: string;
+        coordinatorIdEnvVar: string;
     });
+    /**
+     * Is this instance the coordinator?
+     *
+     * Coordinator status is determined from the coordinatorIdEnvVar environment variable.
+     * The coordinator handles finalization and cleanup of shard files.
+     *
+     * @returns true if this instance is the coordinator, false otherwise
+     */
+    isCoordinator(): boolean;
     shard(shardId?: string): WriteAheadLogFile<T>;
     /** Get all shard file paths matching this WAL's base name */
     private shardFiles;

package/src/lib/wal.js

@@ -216,7 +216,7 @@ export function parseWalFormat(format) {
  *
  * @returns true if this is the leader WAL process, false otherwise
  */
-export function isLeaderWal(envVarName, profilerID) {
+export function isCoordinatorProcess(envVarName, profilerID) {
     return process.env[envVarName] === profilerID;
 }
 /**
@@ -224,7 +224,7 @@ export function isLeaderWal(envVarName, profilerID) {
  * This must be done as early as possible before any user code runs.
  * Sets envVarName to the current process ID if not already defined.
  */
-export function setLeaderWal(envVarName, profilerID) {
+export function setCoordinatorProcess(envVarName, profilerID) {
     if (!process.env[envVarName]) {
         // eslint-disable-next-line functional/immutable-data
         process.env[envVarName] = profilerID;
@@ -232,6 +232,13 @@ export function setLeaderWal(envVarName, profilerID) {
 }
 // eslint-disable-next-line functional/no-let
 let shardCount = 0;
+/**
+ * Generates a unique sharded WAL ID based on performance time origin, process ID, thread ID, and instance count.
+ */
+function getShardedWalId() {
+    // eslint-disable-next-line functional/immutable-data
+    return `${Math.round(performance.timeOrigin)}.${process.pid}.${threadId}.${++ShardedWal.instanceCount}`;
+}
 /**
  * Generates a human-readable shard ID.
  * This ID is unique per process/thread/shard combination and used in the file name.
@@ -316,19 +323,39 @@ export function getShardedFinalPath(opt) {
  * Handles distributed logging across multiple processes/files with atomic finalization.
  */
 export class ShardedWal {
+    static instanceCount = 0;
+    #id = getShardedWalId();
     groupId = getShardedGroupId();
     #format;
     #dir = process.cwd();
+    #isCoordinator;
     /**
      * Create a sharded WAL manager.
+     *
+     * @param opt.dir - Base directory to store shard files (defaults to process.cwd())
+     * @param opt.format - WAL format configuration
+     * @param opt.groupId - Group ID for sharding (defaults to generated group ID)
+     * @param opt.coordinatorIdEnvVar - Environment variable name for storing coordinator ID (defaults to CP_SHARDED_WAL_COORDINATOR_ID)
      */
     constructor(opt) {
-        const { dir, format, groupId } = opt;
+        const { dir, format, groupId, coordinatorIdEnvVar } = opt;
         this.groupId = groupId ?? getShardedGroupId();
         if (dir) {
             this.#dir = dir;
         }
         this.#format = parseWalFormat(format);
+        this.#isCoordinator = isCoordinatorProcess(coordinatorIdEnvVar, this.#id);
+    }
+    /**
+     * Is this instance the coordinator?
+     *
+     * Coordinator status is determined from the coordinatorIdEnvVar environment variable.
+     * The coordinator handles finalization and cleanup of shard files.
+     *
+     * @returns true if this instance is the coordinator, false otherwise
+     */
+    isCoordinator() {
+        return this.#isCoordinator;
     }
     shard(shardId = getShardId()) {
         return new WriteAheadLogFile({