@monochromatic-dev/module-logger 0.1.0

package/src/sink/session-storage.browser.test.ts

@@ -0,0 +1,137 @@
+// oxlint-disable typescript/no-unsafe-assignment, typescript/no-unsafe-member-access, typescript/strict-boolean-expressions -- browser evaluate callbacks lose type info across page boundary
+
+import {
+  expect,
+  test,
+} from '@playwright/test';
+
+declare global {
+  // oxlint-disable-next-line typescript/consistent-type-imports -- typeof import() cannot use import type syntax
+  var moduleLogger: typeof import('@monochromatic-dev/module-logger');
+}
+
+test.describe('sessionStorage sink', () => {
+  test.beforeEach(async ({ page, },) => {
+    await page.goto('/',);
+    await page.waitForFunction(() => globalThis.moduleLogger !== undefined);
+  },);
+
+  test('createSessionStorageSink exposes a callable verify', async ({ page, },) => {
+    const typeofVerify = await page.evaluate(() => {
+      const { createSessionStorageSink, } = globalThis.moduleLogger.sinks;
+      return typeof createSessionStorageSink().verify;
+    },);
+    expect(typeofVerify,).toBe('function',);
+  });
+
+  test('verify resolves a boolean', async ({ page, },) => {
+    const resultType = await page.evaluate(async () => {
+      const { createSessionStorageSink, } = globalThis.moduleLogger.sinks;
+      return typeof (await createSessionStorageSink().verify());
+    },);
+    expect(resultType,).toBe('boolean',);
+  });
+
+  test('verify detects availability', async ({ page, },) => {
+    const result = await page.evaluate(async () => {
+      const { createSessionStorageSink, } = globalThis.moduleLogger.sinks;
+      return createSessionStorageSink().verify();
+    },);
+    expect(result,).toBe(true,);
+  });
+
+  test('sink write method exists', async ({ page, },) => {
+    const typeofSink = await page.evaluate(() => {
+      const { createSessionStorageSink, } = globalThis.moduleLogger.sinks;
+      return typeof createSessionStorageSink().write;
+    },);
+    expect(typeofSink,).toBe('function',);
+  });
+
+  test('a verified sink writes records across levels and message shapes', async ({ page, },) => {
+    const allSucceeded = await page.evaluate(async () => {
+      const { createSessionStorageSink, } = globalThis.moduleLogger.sinks;
+      const sink = createSessionStorageSink();
+      await sink.verify();
+      const levels = ['trace', 'debug', 'info', 'warn', 'error', 'fatal',] as const;
+      const messages = [
+        'test message',
+        'Hello 世界 🌍',
+        '',
+        '{"key": "value", "nested": {"a": 1}}',
+      ];
+      for (const level of levels) {
+        for (const message of messages) {
+          try {
+            void sink.write({
+              level,
+              message,
+              timestamp: Date.now(),
+            },);
+          }
+          catch (error: unknown) {
+            console.warn('sessionStorage sink browser test write failed', error,);
+            return false;
+          }
+        }
+      }
+      return true;
+    },);
+    expect(allSucceeded,).toBe(true,);
+  });
+
+  test('written records can be retrieved from sessionStorage', async ({ page, },) => {
+    const result = await page.evaluate(async () => {
+      const { createSessionStorageSink, } = globalThis.moduleLogger.sinks;
+
+      // Clear any existing logs first.
+      const keysToRemove: string[] = [];
+      const storageLength = globalThis.sessionStorage.length;
+      for (let storageIndex = 0; storageIndex < storageLength; storageIndex++) {
+        const key = globalThis.sessionStorage.key(storageIndex,);
+        if (key?.startsWith('monochromatic.log',))
+          keysToRemove.push(key,);
+      }
+      keysToRemove.forEach(key => {
+        globalThis.sessionStorage.removeItem(key,);
+      },);
+
+      const sink = createSessionStorageSink();
+      await sink.verify();
+
+      const testMessage = `unique-test-${Date.now()}`;
+      await sink.write({
+        level: 'info' as const,
+        message: testMessage,
+        timestamp: Date.now(),
+      },);
+      // Routine severity buffers; the flush hook forces the batch out so the
+      // read-back below observes it deterministically.
+      await sink.flush?.();
+
+      // Find the written record.
+      const currentStorageLength = globalThis.sessionStorage.length;
+      for (let storageIndex = 0; storageIndex < currentStorageLength; storageIndex++) {
+        const key = globalThis.sessionStorage.key(storageIndex,);
+        if (key?.startsWith('monochromatic.log',)) {
+          const value = globalThis.sessionStorage.getItem(key,);
+          if (value?.includes(testMessage,)) {
+            const parsed = JSON.parse(value,);
+            return {
+              found: true,
+              message: parsed.message,
+              level: parsed.level,
+              testMessage,
+            };
+          }
+        }
+      }
+
+      return { found: false, message: null, level: null, testMessage, };
+    },);
+
+    expect(result.found,).toBe(true,);
+    expect(result.message,).toBe(result.testMessage,);
+    expect(result.level,).toBe('info',);
+  });
+});

package/src/sink/session-storage.ts

@@ -0,0 +1,128 @@
+import { reportLoggerInternalError, } from '../error-format.ts';
+import { createRecordBuffer, } from './record-buffer.ts';
+import { createSessionStorageStore, } from './session-storage-store.ts';
+
+import type {
+  Level,
+  Sink,
+} from '../types.ts';
+
+/**
+ * Verifies sessionStorage actually persists data. Stateless: the logger calls
+ * this once per sink at startup and owns the resulting availability, so no
+ * verified/available flag is kept here.
+ *
+ * Election is by probe alone: any runtime whose `sessionStorage` round-trips
+ * (browsers, Node 22+, Deno) keeps the sink, and the buffered write path
+ * keeps the per-record cost acceptable everywhere rather than a runtime brand
+ * check deciding who may log here.
+ *
+ * @returns Whether sessionStorage is available and round-trips a probe write.
+ *
+ * @example
+ * ```ts
+ * if (await verifySessionStorage()) {
+ *   // sessionStorage usable
+ * }
+ * ```
+ */
+function verifySessionStorage(): Promise<boolean> {
+  try {
+    /**
+     * Sentinel key used only for the probe write/read; removed afterward to avoid polluting real log entries.
+     */
+    const testKey = '__monochromatic_verify__';
+    /**
+     * Timestamp-based probe value so concurrent verifications never read each other's writes.
+     */
+    const testValue = `test-${Date.now()}`;
+    globalThis.sessionStorage
+      .setItem(
+      testKey,
+      testValue,
+    );
+    /**
+     * Probe value read back from storage; equality with `testValue` proves writes actually persist.
+     */
+    const readBack = globalThis.sessionStorage
+      .getItem(testKey,);
+    globalThis.sessionStorage
+      .removeItem(testKey,);
+    return Promise.resolve(readBack === testValue,);
+  }
+  catch (error: unknown) {
+    if ('sessionStorage' in globalThis)
+      reportLoggerInternalError({
+        context: 'sessionStorage sink verification failed',
+        error,
+      },);
+    return Promise.resolve(false,);
+  }
+}
+
+/**
+ * Builds a sessionStorage sink that buffers serialized records through the
+ * shared {@link createRecordBuffer} policy and persists each newline-joined
+ * JSONL batch under a counter-incremented key through
+ * {@link createSessionStorageStore}. One uniform write path runs on every
+ * runtime; no per-runtime mode exists. Flush triggers (32 KiB in-write cap,
+ * `warn`-or-worse severity, 250 ms quiet-period deadline, page lifecycle,
+ * and the `flush` hook) are the buffer's; see {@link createRecordBuffer}.
+ *
+ * @returns Sink backed by web `sessionStorage`.
+ *
+ * @example
+ * ```ts
+ * const { logger } = createLogger({ sinks: [createSessionStorageSink()] });
+ * logger.info('user signed in'); // buffered
+ * logger.warn('quota near');     // flushes both records in one batch
+ * ```
+ */
+export function createSessionStorageSink(): Sink {
+  /**
+   * Persistence engine owning key allocation, footprint accounting, and quota
+   * eviction; the buffer decides when a batch is handed to it.
+   */
+  const store = createSessionStorageStore();
+
+  /**
+   * Shared buffering stage; every flush trigger lands one joined batch in the
+   * persistence engine synchronously.
+   */
+  const buffer = createRecordBuffer({ onFlush: store.persist, },);
+
+  /**
+   * Buffers a log record through the shared policy; see
+   * {@link createRecordBuffer} for the flush triggers.
+   *
+   * @param record - Log record to buffer and eventually persist.
+   *
+   * @mutates record - `JSON.stringify` may invoke `toJSON`, getters, or proxy traps.
+   */
+  function write(record: {
+    level: Level;
+    message: string;
+    timestamp: number;
+  },): Promise<void> {
+    buffer.add({
+      level: record.level,
+      serialized: JSON.stringify(record,),
+    },);
+    return Promise.resolve();
+  }
+
+  /**
+   * Drains the buffer into the persistence engine; the drain is synchronous,
+   * so the batch has landed by the time the resolved promise is observed.
+   */
+  function flush(): Promise<void> {
+    buffer.drain();
+    return Promise.resolve();
+  }
+
+  return {
+    flush,
+    verify: verifySessionStorage,
+    write,
+  };
+}