feat: logger transporters

Author: KatoakDR

electron/main/logger/transport/__tests__/console-transporter.test.ts

@@ -0,0 +1,52 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { LogLevel, type LogMessage } from '../../../../common/logger/types.js';
+import type { LogFormatterMock } from '../../__mocks__/log-formatter.mock.js';
+import { LogFormatterMockImpl } from '../../__mocks__/log-formatter.mock.js';
+import { ConsoleLogTransporterImpl } from '../console.transporter.js';
+
+describe('console-log-transporter', () => {
+  let mockLogMessage: LogMessage;
+  let mockFormatter: LogFormatterMock;
+
+  let transporter: ConsoleLogTransporterImpl;
+
+  beforeEach(() => {
+    mockLogMessage = {
+      level: LogLevel.INFO,
+      scope: 'test-scope',
+      message: 'test-message',
+      timestamp: new Date(),
+      data: {},
+    };
+
+    mockFormatter = new LogFormatterMockImpl();
+
+    transporter = new ConsoleLogTransporterImpl({
+      formatter: mockFormatter,
+    });
+  });
+
+  afterEach(() => {
+    vi.resetAllMocks();
+  });
+
+  describe('#transport', () => {
+    it('should log the message to the console', () => {
+      const consoleInfoSpy = vi.spyOn(console, 'info');
+
+      transporter.transport(mockLogMessage);
+
+      expect(consoleInfoSpy).toHaveBeenCalledWith(mockLogMessage);
+    });
+
+    it('should log the formatted message to the console', () => {
+      mockFormatter.format.mockReturnValue('test-formatted-message');
+
+      const consoleInfoSpy = vi.spyOn(console, 'info');
+
+      transporter.transport(mockLogMessage);
+
+      expect(consoleInfoSpy).toHaveBeenCalledWith('test-formatted-message');
+    });
+  });
+});

electron/main/logger/transport/__tests__/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../../tsconfig.test.json"
+}

electron/main/logger/transport/console.transporter.ts

@@ -0,0 +1,39 @@
+import type {
+  LogMessage,
+  LogTransporter,
+} from '../../../common/logger/types.js';
+import { LogLevel } from '../../../common/logger/types.js';
+import type { LogFormatter } from '../types.js';
+
+/**
+ * Transports logs to the console.
+ */
+export class ConsoleLogTransporterImpl implements LogTransporter {
+  private formatter?: LogFormatter;
+
+  constructor(options?: { formatter?: LogFormatter }) {
+    this.formatter = options?.formatter;
+  }
+
+  public transport(message: LogMessage): void {
+    const formattedMessage = this.formatter?.format(message) ?? message;
+
+    switch (message.level) {
+      case LogLevel.ERROR:
+        console.error(formattedMessage);
+        break;
+      case LogLevel.WARN:
+        console.warn(formattedMessage);
+        break;
+      case LogLevel.INFO:
+        console.info(formattedMessage);
+        break;
+      case LogLevel.DEBUG:
+      case LogLevel.TRACE:
+        console.debug(formattedMessage);
+        break;
+      default:
+        console.log(formattedMessage);
+    }
+  }
+}

electron/main/logger/transport/file.transporter.ts

@@ -0,0 +1,38 @@
+import fs from 'fs-extra';
+import type { LogFormatter } from '../types.js';
+import { WritableLogTransporterImpl } from './writable.transporter.js';
+
+/**
+ * Transports logs to a text file.
+ */
+export class FileLogTransporterImpl extends WritableLogTransporterImpl {
+  constructor(options: {
+    /**
+     * Path where to write the logs.
+     */
+    filePath: string;
+    /**
+     * If true, the log messages will be appended to the file.
+     * If false, the file will be overwritten.
+     * Default is true.
+     */
+    append?: boolean;
+    /**
+     * The text encoding to use when writing the file.
+     * Default is 'utf8'.
+     */
+    encoding?: BufferEncoding;
+    /**
+     * Optional to format the log messages before writing them.
+     */
+    formatter?: LogFormatter;
+  }) {
+    super({
+      writable: fs.createWriteStream(options.filePath, {
+        flags: options.append ? 'a' : 'w',
+        encoding: options.encoding ?? 'utf8',
+      }),
+      ...options,
+    });
+  }
+}

electron/main/logger/transport/writable.transporter.ts

@@ -0,0 +1,97 @@
+import { nextTick } from 'node:process';
+import type { Writable } from 'node:stream';
+import type {
+  LogMessage,
+  LogTransporter,
+} from '../../../common/logger/types.js';
+import type { LogFormatter } from '../types.js';
+
+/**
+ * Transports logs via a {@link Writable} stream.
+ */
+export class WritableLogTransporterImpl implements LogTransporter {
+  // To allow for asynchronous writing of logs without the use of promises,
+  // we use a recursive-like queue draining algorithm. This provides an
+  // ergonomic API while still allowing for asynchronous writing.
+  // This also allows us to buffer when we need to wait for the writer to drain.
+  private asyncWriteQueue = new Array<LogMessage>();
+  private asyncWriteInProgress = false;
+
+  private writer: Writable;
+  private formatter?: LogFormatter;
+
+  constructor(options: {
+    /**
+     * Where to write the log messages.
+     */
+    writable: Writable;
+    /**
+     * Optional to format the log messages before writing them.
+     */
+    formatter?: LogFormatter;
+  }) {
+    this.formatter = options?.formatter;
+    this.writer = options.writable;
+
+    this.writer.on('error', (error) => {
+      this.callback(error);
+    });
+  }
+
+  public transport(message: LogMessage): void {
+    // We queue messages to write then process them in the background
+    // to allow for asynchronous writing of logs without the use of promises
+    // so that the use of our logger doesn't require 'await' everywhere.
+    // And to buffer when we need to wait for the writer to drain.
+    this.asyncWriteQueue.push(message);
+
+    // Ensure the log is written asynchronously, but soonish.
+    nextTick(() => {
+      this.writeNextMessageAsync();
+    });
+  }
+
+  protected writeNextMessageAsync(): void {
+    if (this.asyncWriteInProgress || this.asyncWriteQueue.length === 0) {
+      return;
+    }
+
+    const message = this.asyncWriteQueue.shift();
+    if (!message) {
+      this.callback();
+      return;
+    }
+
+    this.asyncWriteInProgress = true;
+
+    try {
+      const formattedMessage = this.formatter?.format(message) ?? message;
+
+      const doDrain = !this.writer.write(formattedMessage);
+
+      if (doDrain) {
+        this.writer.once('drain', () => {
+          this.callback();
+        });
+      } else {
+        this.callback();
+      }
+    } catch (error) {
+      this.callback(error);
+    }
+  }
+
+  protected callback(error?: Error | null): void {
+    if (error) {
+      console.error('[LOGGER:WRITE:ERROR]', error);
+    }
+
+    this.asyncWriteInProgress = false;
+
+    // Now check for more messages to write.
+    // Using `nextTick` avoids stack overflow when the queue is large.
+    nextTick(() => {
+      this.writeNextMessageAsync();
+    });
+  }
+}