refactor: wip

Author: BioPhoton

packages/utils/src/lib/profiler/wal-json-trace.ts

@@ -1,4 +1,4 @@
-import { performance } from 'node:perf_hooks';
+import { defaultClock } from '../clock-epoch.js';
 import type { InvalidEntry, WalFormat } from '../wal.js';
 import {
   decodeTraceEvent,
@@ -13,10 +13,10 @@ import type { TraceEvent, UserTimingTraceEvent } from './trace-file.type.js';
 const TRACE_START_MARGIN_NAME = '[trace padding start]';
 /** Name for the trace end margin event */
 const TRACE_END_MARGIN_NAME = '[trace padding end]';
-/** Milliseconds of padding to add before/after trace events */
-const TRACE_MARGIN_MS = 1000;
-/** Duration in milliseconds for margin events */
-const TRACE_MARGIN_DURATION_MS = 20;
+/** Microseconds of padding to add before/after trace events (1000ms = 1,000,000μs) */
+const TRACE_MARGIN_US = 1_000_000;
+/** Duration in microseconds for margin events (20ms = 20,000μs) */
+const TRACE_MARGIN_DURATION_US = 20_000;
 
 /**
  * Generates a complete Chrome DevTools trace file content as JSON string.
@@ -38,16 +38,16 @@ export function generateTraceContent(
     },
   });
 
-  const marginMs = TRACE_MARGIN_MS;
-  const marginDurMs = TRACE_MARGIN_DURATION_MS;
+  const marginUs = TRACE_MARGIN_US;
+  const marginDurUs = TRACE_MARGIN_DURATION_US;
 
   const sortedEvents = [...events].sort((a, b) => a.ts - b.ts);
-  const fallbackTs = performance.now();
+  const fallbackTs = defaultClock.epochNowUs();
   const firstTs: number = sortedEvents.at(0)?.ts ?? fallbackTs;
   const lastTs: number = sortedEvents.at(-1)?.ts ?? fallbackTs;
 
-  const startTs = firstTs - marginMs;
-  const endTs = lastTs + marginMs;
+  const startTs = firstTs - marginUs;
+  const endTs = lastTs + marginUs;
 
   const traceEvents: TraceEvent[] = [
     getInstantEventTracingStartedInBrowser({
@@ -57,13 +57,13 @@ export function generateTraceContent(
     getCompleteEvent({
       name: TRACE_START_MARGIN_NAME,
       ts: startTs,
-      dur: marginDurMs,
+      dur: marginDurUs,
     }),
     ...sortedEvents,
     getCompleteEvent({
       name: TRACE_END_MARGIN_NAME,
       ts: endTs,
-      dur: marginDurMs,
+      dur: marginDurUs,
     }),
   ];
 

packages/utils/src/lib/profiler/wal-json-trace.unit.test.ts

@@ -28,13 +28,13 @@ describe('generateTraceContent', () => {
         expect.objectContaining({
           name: '[trace padding start]',
           ph: 'X',
-          dur: 20,
+          dur: 20_000,
           cat: 'devtools.timeline',
         }),
         expect.objectContaining({
           name: '[trace padding end]',
           ph: 'X',
-          dur: 20,
+          dur: 20_000,
           cat: 'devtools.timeline',
         }),
       ],
@@ -102,14 +102,14 @@ describe('generateTraceContent', () => {
         expect.objectContaining({
           name: '[trace padding start]',
           ph: 'X',
-          dur: 20,
+          dur: 20_000,
           cat: 'devtools.timeline',
         }),
         ...events,
         expect.objectContaining({
           name: '[trace padding end]',
           ph: 'X',
-          dur: 20,
+          dur: 20_000,
           cat: 'devtools.timeline',
         }),
       ],
@@ -191,24 +191,24 @@ describe('generateTraceContent', () => {
       }),
     );
 
-    // Second should be start margin at ts - 1000
+    // Second should be start margin at ts - 1,000,000μs (1000ms)
     expect(traceEvents[1]).toStrictEqual(
       expect.objectContaining({
         name: '[trace padding start]',
         ph: 'X',
-        dur: 20,
+        dur: 20_000,
       }),
     );
 
     // Third should be the actual event
     expect(traceEvents[2]).toStrictEqual(events[0]);
 
-    // Fourth should be end margin at lastTs + 1000
+    // Fourth should be end margin at lastTs + 1,000,000μs (1000ms)
     expect(traceEvents[3]).toStrictEqual(
       expect.objectContaining({
         name: '[trace padding end]',
         ph: 'X',
-        dur: 20,
+        dur: 20_000,
       }),
     );
   });

packages/utils/src/lib/wal.ts

@@ -38,6 +38,22 @@ export type RecoverResult<T> = {
   partialTail: string | null;
 };
 
+/**
+ * Statistics about the WAL file state and last recovery operation.
+ */
+export type WalStats<T> = {
+  /** File path for this WAL */
+  filePath: string;
+  /** Whether the WAL file is currently closed */
+  isClosed: boolean;
+  /** Whether the WAL file exists on disk */
+  fileExists: boolean;
+  /** File size in bytes (0 if file doesn't exist) */
+  fileSize: number;
+  /** Last recovery state from the most recent {@link recover} or {@link repack} operation */
+  lastRecovery: RecoverResult<T | InvalidEntry<string>> | null;
+};
+
 export const createTolerantCodec = <I, O = string>(codec: {
   encode: (v: I) => O;
   decode: (d: O) => I;
@@ -121,6 +137,7 @@ export class WriteAheadLogFile<T> implements AppendableSink<T> {
   readonly #file: string;
   readonly #decode: Codec<T | InvalidEntry<string>>['decode'];
   readonly #encode: Codec<T>['encode'];
+  #lastRecoveryState: RecoverResult<T | InvalidEntry<string>> | null = null;
 
   /**
    * Create a new WAL file instance.
@@ -170,20 +187,27 @@ export class WriteAheadLogFile<T> implements AppendableSink<T> {
   /**
    * Recover all records from the WAL file.
    * Handles partial writes and decode errors gracefully.
+   * Updates the recovery state (accessible via {@link getStats}).
    * @returns Recovery result with records, errors, and partial tail
    */
   recover(): RecoverResult<T | InvalidEntry<string>> {
     if (!fs.existsSync(this.#file)) {
-      return { records: [], errors: [], partialTail: null };
+      this.#lastRecoveryState = { records: [], errors: [], partialTail: null };
+      return this.#lastRecoveryState;
     }
-
     const txt = fs.readFileSync(this.#file, 'utf8');
-    return recoverFromContent<T | InvalidEntry<string>>(txt, this.#decode);
+    this.#lastRecoveryState = recoverFromContent<T | InvalidEntry<string>>(
+      txt,
+      this.#decode,
+    );
+
+    return this.#lastRecoveryState;
   }
 
   /**
    * Repack the WAL by recovering all valid records and rewriting cleanly.
    * Removes corrupted entries and ensures clean formatting.
+   * Updates the recovery state (accessible via {@link getStats}).
    * @param out - Output path (defaults to current file)
    */
   repack(out = this.#file) {
@@ -208,6 +232,22 @@ export class WriteAheadLogFile<T> implements AppendableSink<T> {
     fs.mkdirSync(path.dirname(out), { recursive: true });
     fs.writeFileSync(out, `${recordsToWrite.map(this.#encode).join('\n')}\n`);
   }
+
+  /**
+   * Get comprehensive statistics about the WAL file state.
+   * Includes file information, open/close status, and last recovery state.
+   * @returns Statistics object with file info and last recovery state
+   */
+  getStats(): WalStats<T> {
+    const fileExists = fs.existsSync(this.#file);
+    return {
+      filePath: this.#file,
+      isClosed: this.#fd == null,
+      fileExists,
+      fileSize: fileExists ? fs.statSync(this.#file).size : 0,
+      lastRecovery: this.#lastRecoveryState,
+    };
+  }
 }
 
 /**
@@ -246,7 +286,7 @@ export const stringCodec = <
 /**
  * Parses a partial WalFormat configuration and returns a complete WalFormat object.
  * All fallback values are targeting string types.
- *  - baseName defaults to Date.now().toString()
+ *  - baseName defaults to 'wal'
  *  - walExtension defaults to '.log'
  *  - finalExtension defaults to '.log'
  *  - codec defaults to stringCodec<T>()
@@ -258,14 +298,23 @@ export function parseWalFormat<T extends object | string = object>(
   format: Partial<WalFormat<T>>,
 ): WalFormat<T> {
   const {
-    baseName = 'trace',
+    baseName = 'wal',
     walExtension = '.log',
     finalExtension = walExtension,
     codec = stringCodec<T>(),
-    finalizer = (encodedRecords: (T | InvalidEntry<string>)[]) =>
-      `${encodedRecords.join('\n')}\n`,
   } = format;
 
+  const finalizer =
+    format.finalizer ??
+    ((encodedRecords: (T | InvalidEntry<string>)[]) => {
+      const encoded = encodedRecords.map(record =>
+        typeof record === 'object' && record != null && '__invalid' in record
+          ? (record as InvalidEntry<string>).raw
+          : codec.encode(record as T),
+      );
+      return `${encoded.join('\n')}\n`;
+    });
+
   return {
     baseName,
     walExtension,
@@ -301,6 +350,7 @@ export function setLeaderWal(envVarName: string, profilerID: string): void {
 
 // eslint-disable-next-line functional/no-let
 let shardCount = 0;
+
 /**
  * Generates a human-readable shard ID.
  * This ID is unique per process/thread/shard combination and used in the file name.
@@ -354,6 +404,7 @@ export function sortableReadableDateString(timestampMs: string): string {
 
   return `${yyyy}${mm}${dd}-${hh}${min}${ss}-${ms}`;
 }
+
 /**
  * Generates a path to a shard file using human-readable IDs.
  * Both groupId and shardId are already in readable date format.

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

@@ -572,7 +572,7 @@ describe('parseWalFormat', () => {
   it('should apply all defaults when given empty config', () => {
     const result = parseWalFormat({});
 
-    expect(result.baseName).toBe('trace');
+    expect(result.baseName).toBe('wal');
     expect(result.walExtension).toBe('.log');
     expect(result.finalExtension).toBe('.log');
     expect(result.codec).toBeDefined();
@@ -641,6 +641,27 @@ describe('parseWalFormat', () => {
     expect(result.finalizer(['line1', 'line2'])).toBe('line1\nline2\n');
     expect(result.finalizer([])).toBe('\n');
   });
+
+  it('should encode objects to JSON strings in default finalizer', () => {
+    const result = parseWalFormat<object>({ baseName: 'test' });
+    const records = [
+      { id: 1, name: 'test' },
+      { id: 2, name: 'test2' },
+    ];
+    const output = result.finalizer(records);
+    expect(output).toBe('{"id":1,"name":"test"}\n{"id":2,"name":"test2"}\n');
+  });
+
+  it('should handle InvalidEntry in default finalizer', () => {
+    const result = parseWalFormat<string>({ baseName: 'test' });
+    const records: (string | InvalidEntry<string>)[] = [
+      'valid',
+      { __invalid: true, raw: 'invalid-raw' },
+      'also-valid',
+    ];
+    const output = result.finalizer(records);
+    expect(output).toBe('valid\ninvalid-raw\nalso-valid\n');
+  });
 });
 
 describe('isLeaderWal', () => {