@monochromatic-dev/module-logger 0.1.0

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

@@ -0,0 +1,125 @@
+// 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('localStorage sink', () => {
+  test.beforeEach(async ({ page, },) => {
+    await page.goto('/',);
+    await page.waitForFunction(() => globalThis.moduleLogger !== undefined);
+  },);
+
+  test('createLocalStorageSink exposes a callable verify', async ({ page, },) => {
+    const typeofVerify = await page.evaluate(() => {
+      const { createLocalStorageSink, } = globalThis.moduleLogger.sinks;
+      return typeof createLocalStorageSink().verify;
+    },);
+    expect(typeofVerify,).toBe('function',);
+  });
+
+  test('verify detects availability', async ({ page, },) => {
+    const result = await page.evaluate(async () => {
+      const { createLocalStorageSink, } = globalThis.moduleLogger.sinks;
+      return createLocalStorageSink().verify();
+    },);
+    expect(result,).toBe(true,);
+  });
+
+  test('a verified sink writes records across levels and message shapes', async ({ page, },) => {
+    const allSucceeded = await page.evaluate(async () => {
+      const { createLocalStorageSink, } = globalThis.moduleLogger.sinks;
+      const sink = createLocalStorageSink();
+      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('localStorage sink browser test write failed', error,);
+            return false;
+          }
+        }
+      }
+      return true;
+    },);
+    expect(allSucceeded,).toBe(true,);
+  });
+
+  test('written records can be retrieved from localStorage under a run-scoped key', async ({ page, },) => {
+    const result = await page.evaluate(async () => {
+      const { createLocalStorageSink, } = globalThis.moduleLogger.sinks;
+
+      // Clear any existing logs first.
+      const keysToRemove: string[] = [];
+      const storageLength = globalThis.localStorage.length;
+      for (let storageIndex = 0; storageIndex < storageLength; storageIndex++) {
+        const key = globalThis.localStorage.key(storageIndex,);
+        if (key?.startsWith('monochromatic.log',))
+          keysToRemove.push(key,);
+      }
+      keysToRemove.forEach(key => {
+        globalThis.localStorage.removeItem(key,);
+      },);
+
+      const sink = createLocalStorageSink();
+      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 under a run-scoped key
+      // (`monochromatic.log.{stamp}.{nonce}.{index}`).
+      const currentStorageLength = globalThis.localStorage.length;
+      for (let storageIndex = 0; storageIndex < currentStorageLength; storageIndex++) {
+        const key = globalThis.localStorage.key(storageIndex,);
+        if (key?.startsWith('monochromatic.log',)) {
+          const value = globalThis.localStorage.getItem(key,);
+          if (value?.includes(testMessage,)) {
+            const parsed = JSON.parse(value,);
+            return {
+              found: true,
+              message: parsed.message,
+              level: parsed.level,
+              keySegments: key.split('.',).length,
+              testMessage,
+            };
+          }
+        }
+      }
+
+      return { found: false, message: null, level: null, keySegments: 0, testMessage, };
+    },);
+
+    expect(result.found,).toBe(true,);
+    expect(result.message,).toBe(result.testMessage,);
+    expect(result.level,).toBe('info',);
+    // Prefix `monochromatic.log` plus stamp, nonce, and index.
+    expect(result.keySegments,).toBe(5,);
+  });
+});

package/src/sink/local-storage.ts

@@ -0,0 +1,182 @@
+import { reportLoggerInternalError, } from '../error-format.ts';
+import { createLocalStorageStore, } from './local-storage-store.ts';
+import { createRecordBuffer, } from './record-buffer.ts';
+import { detectWebStorageRuntime, } from './web-storage-runtime.ts';
+
+import type {
+  Level,
+  Sink,
+} from '../types.ts';
+
+/**
+ * Node CLI flag that backs `localStorage` with a file; without it Node 26
+ * leaves `globalThis.localStorage` undefined and prints an
+ * `ExperimentalWarning` on stderr the moment the getter is touched.
+ */
+const NODE_LOCALSTORAGE_FLAG = '--localstorage-file';
+
+/**
+ * Reports whether this is a flagless plain-Node process, where
+ * `globalThis.localStorage` is undefined and merely touching the getter
+ * prints Node's ExperimentalWarning on stderr for every consumer, so `verify`
+ * skips the probe without any access. The flag is honored both on the command
+ * line (`process.execArgv`) and through `NODE_OPTIONS` (verified on Node 26;
+ * `execArgv` does not echo `NODE_OPTIONS` flags, so both are checked). A DOM
+ * host (such as an Electron renderer, which carries `process.versions.node`
+ * alongside a real `localStorage`) is exempt and probes normally.
+ *
+ * @returns Whether the probe must be skipped because Node would only warn.
+ */
+function nodeWithoutLocalStorageFile(): boolean {
+  if (detectWebStorageRuntime() !== 'node')
+    return false;
+  if ('document' in globalThis)
+    return false;
+  /**
+   * Whether the backing-file flag reached this process on the command line.
+   */
+  const flaggedInExecArgv = process.execArgv
+    .some(function startsWithFlag(argument: string,) {
+      return argument.startsWith(NODE_LOCALSTORAGE_FLAG,);
+    },);
+  /**
+   * Raw `NODE_OPTIONS` value, absent when the variable is unset; `execArgv`
+   * does not echo flags arriving through it, so it is scanned separately.
+   */
+  const nodeOptions = process.env
+    .NODE_OPTIONS;
+  /**
+   * Whether the backing-file flag reached this process through `NODE_OPTIONS`.
+   */
+  const flaggedInNodeOptions = (nodeOptions ?? '').includes(NODE_LOCALSTORAGE_FLAG,);
+  return !(flaggedInExecArgv || flaggedInNodeOptions);
+}
+
+/**
+ * Verifies localStorage 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 `localStorage` round-trips
+ * (browsers, Deno, Node launched with `--localstorage-file`) keeps the sink.
+ * The one short-circuit, {@link nodeWithoutLocalStorageFile}, returns the
+ * same `false` the probe would and exists only to keep Node's access warning
+ * off every consumer's stderr, not to gate by runtime brand.
+ *
+ * @returns Whether localStorage is available and round-trips a probe write.
+ *
+ * @example
+ * ```ts
+ * if (await verifyLocalStorage()) {
+ *   // localStorage usable
+ * }
+ * ```
+ */
+function verifyLocalStorage(): Promise<boolean> {
+  if (nodeWithoutLocalStorageFile())
+    return Promise.resolve(false,);
+  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.localStorage
+      .setItem(
+      testKey,
+      testValue,
+    );
+    /**
+     * Probe value read back from storage; equality with `testValue` proves writes actually persist.
+     */
+    const readBack = globalThis.localStorage
+      .getItem(testKey,);
+    globalThis.localStorage
+      .removeItem(testKey,);
+    return Promise.resolve(readBack === testValue,);
+  }
+  catch (error: unknown) {
+    if ('localStorage' in globalThis)
+      reportLoggerInternalError({
+        context: 'localStorage sink verification failed',
+        error,
+      },);
+    return Promise.resolve(false,);
+  }
+}
+
+/**
+ * Builds a localStorage sink that buffers serialized records through the
+ * shared {@link createRecordBuffer} policy and persists each newline-joined
+ * JSONL batch under a run-scoped counter-incremented key through
+ * {@link createLocalStorageStore}. 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}.
+ *
+ * Unlike the sessionStorage sink, whose store dies with the tab, this sink's
+ * batches survive tab close and browser restart, bounded by oldest-first
+ * eviction at half the localStorage quota; that makes it the web storage sink
+ * whose records remain inspectable after a full crash-and-restart.
+ *
+ * @returns Sink backed by web `localStorage`.
+ *
+ * @example
+ * ```ts
+ * const { logger } = createLogger({ sinks: [createLocalStorageSink()] });
+ * logger.info('user signed in'); // buffered
+ * logger.warn('quota near');     // flushes both records in one batch
+ * ```
+ */
+export function createLocalStorageSink(): Sink {
+  /**
+   * Persistence engine owning run identity, key allocation, prior-run
+   * adoption, footprint accounting, and quota eviction; the buffer decides
+   * when a batch is handed to it.
+   */
+  const store = createLocalStorageStore();
+
+  /**
+   * 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: verifyLocalStorage,
+    write,
+  };
+}

package/src/sink/local-storage.unit.test.ts

@@ -0,0 +1,218 @@
+import {
+  describe,
+  expect,
+  it,
+} from '@monochromatic-dev/module-test/ts';
+import {
+  _parseLogKey as parseLogKey,
+  sinks,
+} from '@monochromatic-dev/module-logger';
+
+/**
+ * Sink factories under test, read from the built artifact's `sinks` namespace.
+ */
+const {
+  createLocalStorageSink,
+} = sinks;
+
+/**
+ * Installs `fake` as `globalThis.localStorage` via the property descriptor,
+ * restoring the original descriptor, or removing the property when none
+ * existed, when the returned guard leaves `using` scope.
+ *
+ * @param fake - Storage stand-in to install for the duration of the scope.
+ *
+ * @returns Disposable that restores the original `localStorage` on exit.
+ */
+function installFakeLocalStorage(fake: Storage,): Disposable {
+  const original = Object.getOwnPropertyDescriptor(globalThis, 'localStorage',);
+  Object.defineProperty(globalThis, 'localStorage', {
+    configurable: true,
+    value: fake,
+  },);
+  return {
+    [Symbol.dispose](): void {
+      if (original === undefined)
+        Reflect.deleteProperty(globalThis, 'localStorage',);
+      else
+        Object.defineProperty(globalThis, 'localStorage', original,);
+    },
+  };
+}
+
+/**
+ * Installs a minimal fake `globalThis.document` (absent under Node) so the
+ * sink under test takes the DOM-host verify path instead of the flagless-Node
+ * short-circuit, restoring or removing the global when the returned guard
+ * leaves `using` scope.
+ *
+ * @returns Disposable that restores the original `document` on exit.
+ */
+function installFakeDocument(): Disposable {
+  const had = 'document' in globalThis;
+  const original = globalThis.document;
+  globalThis.document = {
+    addEventListener(): void {},
+    visibilityState: 'visible',
+  } as unknown as Document;
+  return {
+    [Symbol.dispose](): void {
+      if (had)
+        globalThis.document = original;
+      else
+        Reflect.deleteProperty(globalThis, 'document',);
+    },
+  };
+}
+
+/**
+ * Builds an in-memory `Storage` stand-in with enumeration support, exposing
+ * the raw `backing` map so a test can assert exactly which keys and values
+ * landed.
+ *
+ * @returns Storage stand-in exposing the raw `backing` map.
+ */
+function createFakeStorage(): Storage & { readonly backing: Map<string, string>; } {
+  const backing = new Map<string, string>();
+  return {
+    backing,
+    get length() {
+      return backing.size;
+    },
+    key(slot: number,) {
+      return [...backing.keys(),][slot] ?? null;
+    },
+    clear(): void {
+      backing.clear();
+    },
+    getItem(key: string,) {
+      return backing.get(key,) ?? null;
+    },
+    setItem(key: string, value: string,): void {
+      backing.set(key, value,);
+    },
+    removeItem(key: string,): void {
+      backing.delete(key,);
+    },
+  } as unknown as Storage & { readonly backing: Map<string, string>; };
+}
+
+/**
+ * Captures `console.warn` output, restoring the real method when the returned
+ * guard leaves `using` scope, so a test can prove the flagless-Node
+ * short-circuit stays silent.
+ *
+ * @returns Disposable exposing captured warn lines as `calls`.
+ */
+function spyConsoleWarn(): Disposable & { readonly calls: string[]; } {
+  const original = console.warn;
+  const calls: string[] = [];
+  console.warn = (...args: unknown[]): void => {
+    calls.push(args.map(String,)
+      .join(' ',),);
+  };
+  return {
+    calls,
+    [Symbol.dispose](): void {
+      console.warn = original;
+    },
+  };
+}
+
+// Serial because tests swap the process-global `localStorage` and `document`,
+// and the flagless-Node test depends on both staying absent.
+await describe({
+  name: createLocalStorageSink.name,
+  concurrency: 1,
+  children: [
+    it({
+      name: 'verify resolves false on flagless Node without touching the getter or reporting',
+      fn: async () => {
+        using warnSpy = spyConsoleWarn();
+        const sink = createLocalStorageSink();
+        expect(await sink.verify(),)
+          .toBe(false,);
+        // A silent skip: no internal-error report and, because the getter was
+        // never touched, no ExperimentalWarning from Node either.
+        expect(warnSpy.calls,)
+          .toHaveLength(0,);
+      },
+    },),
+
+    it({
+      name: 'verify round-trips against an installed storage on a DOM host and cleans its probe',
+      fn: async () => {
+        using _document = installFakeDocument();
+        const fake = createFakeStorage();
+        using _storage = installFakeLocalStorage(fake,);
+        const sink = createLocalStorageSink();
+
+        expect(await sink.verify(),)
+          .toBe(true,);
+        expect(fake.backing.size,)
+          .toBe(0,);
+      },
+    },),
+
+    it({
+      name: 'a warn record lands buffered records as one run-scoped JSONL batch',
+      fn: async () => {
+        using _document = installFakeDocument();
+        const fake = createFakeStorage();
+        using _storage = installFakeLocalStorage(fake,);
+        const sink = createLocalStorageSink();
+
+        /**
+         * Routine record that must stay buffered on its own.
+         */
+        const first = {
+          level: 'info' as const,
+          message: 'first',
+          timestamp: 1,
+        };
+        /**
+         * Urgent record whose severity flushes itself and `first` together.
+         */
+        const second = {
+          level: 'warn' as const,
+          message: 'second',
+          timestamp: 2,
+        };
+
+        await sink.write(first,);
+        expect(fake.backing.size,)
+          .toBe(0,);
+
+        await sink.write(second,);
+        expect([...fake.backing.values(),],)
+          .toEqual([`${JSON.stringify(first,)}\n${JSON.stringify(second,)}`,],);
+        /**
+         * Identity of the landed key; the first batch of a run takes index zero.
+         */
+        const { parsed: landed, } = parseLogKey([...fake.backing.keys(),][0] ?? '',);
+        expect(landed?.index,)
+          .toBe(0,);
+      },
+    },),
+
+    it({
+      name: 'the flush hook drains a buffered routine record synchronously',
+      fn: async () => {
+        using _document = installFakeDocument();
+        const fake = createFakeStorage();
+        using _storage = installFakeLocalStorage(fake,);
+        const sink = createLocalStorageSink();
+
+        await sink.write({
+          level: 'info',
+          message: 'buffered until flush',
+          timestamp: 3,
+        },);
+        await sink.flush?.();
+
+        expect([...fake.backing.values(),].join('|',),)
+          .toContain('buffered until flush',);
+      },
+    },),
+  ],
+},);

package/src/sink/noop.ts

@@ -0,0 +1,46 @@
+import type {
+  LogRecord,
+  Sink,
+} from '../types.ts';
+
+/**
+ * Noop verification: the sink is always available, so it never throws nor
+ * needs setup.
+ *
+ * @returns Always-resolved `true`.
+ */
+function verify(): Promise<boolean> {
+  return Promise.resolve(true,);
+}
+
+/**
+ * Discards a log record. Matches the `Sink['write']` signature.
+ *
+ * @param _record - Log record to discard.
+ */
+function write(_record: LogRecord,): Promise<void> {
+  // Intentionally discards all logs; resolves immediately to match the async Sink contract.
+  return Promise.resolve();
+}
+
+/**
+ * Builds a noop sink that discards every record and always verifies as
+ * available. Stateless, so the returned adapters share the same functions;
+ * the factory shape merely matches the other sinks. Useful as a stand-in
+ * that disables logging without removing log calls.
+ *
+ * @returns Sink that discards all records and exposes no `flush` (nothing
+ * is buffered).
+ *
+ * @example
+ * ```ts
+ * const { logger } = createLogger({ sinks: [createNoopSink()] });
+ * logger.info('goes nowhere');
+ * ```
+ */
+export function createNoopSink(): Sink {
+  return {
+    verify,
+    write,
+  };
+}

package/src/sink/noop.unit.test.ts

@@ -0,0 +1,47 @@
+import {
+  describe,
+  expect,
+  it,
+} from '@monochromatic-dev/module-test/ts';
+import {
+  sinks,
+} from '@monochromatic-dev/module-logger';
+
+/**
+ * Sink factories under test, read from the built artifact's `sinks` namespace.
+ */
+const {
+  createNoopSink,
+} = sinks;
+
+await describe({
+  name: 'noop sink',
+  children: [
+    it({
+      name: 'verifies as available',
+      fn: async () => {
+        const sink = createNoopSink();
+        expect(await sink.verify(),)
+          .toBe(true,);
+      },
+    },),
+
+    it({
+      name: 'discards writes without throwing and exposes no flush hook',
+      fn: async () => {
+        const sink = createNoopSink();
+        await expect(
+          sink.write({
+            level: 'info',
+            message: 'discarded',
+            timestamp: 0,
+          },),
+        )
+          .resolves
+          .toBeUndefined();
+        expect(sink.flush,)
+          .toBeUndefined();
+      },
+    },),
+  ],
+},);

package/src/sink/opfs.browser.test.ts

@@ -0,0 +1,84 @@
+// oxlint-disable eslint/no-await-in-loop -- 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('OPFS sink', () => {
+  test.beforeEach(async ({ page, },) => {
+    await page.goto('/',);
+    await page.waitForFunction(() => globalThis.moduleLogger !== undefined);
+  },);
+
+  test('createOpfsSink exposes a callable verify', async ({ page, },) => {
+    const typeofVerify = await page.evaluate(() => {
+      const { createOpfsSink, } = globalThis.moduleLogger.sinks;
+      return typeof createOpfsSink().verify;
+    },);
+    expect(typeofVerify,).toBe('function',);
+  });
+
+  test('verify resolves a boolean', async ({ page, },) => {
+    const resultType = await page.evaluate(async () => {
+      const { createOpfsSink, } = globalThis.moduleLogger.sinks;
+      const resolved = await createOpfsSink().verify();
+      return typeof resolved;
+    },);
+    expect(resultType,).toBe('boolean',);
+  });
+
+  test('verify detects OPFS availability', async ({ page, },) => {
+    const result = await page.evaluate(async () => {
+      const { createOpfsSink, } = globalThis.moduleLogger.sinks;
+      return createOpfsSink().verify();
+    },);
+    expect(result,).toBe(true,);
+  });
+
+  test('sink write method exists', async ({ page, },) => {
+    const typeofSink = await page.evaluate(() => {
+      const { createOpfsSink, } = globalThis.moduleLogger.sinks;
+      return typeof createOpfsSink().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 { createOpfsSink, } = globalThis.moduleLogger.sinks;
+      const sink = createOpfsSink();
+      await sink.verify();
+      const levels = ['trace', 'debug', 'info', 'warn', 'error', 'fatal',] as const;
+      const messages = [
+        'test message',
+        'Hello 世界 🌍',
+        '',
+        '{"key": "value", "nested": {"a": 1}}',
+        'line1\nline2\nline3',
+      ];
+      for (const level of levels) {
+        for (const message of messages) {
+          try {
+            await Promise.resolve(sink.write({
+              level,
+              message,
+              timestamp: Date.now(),
+            },),);
+          }
+          catch (error: unknown) {
+            console.warn('OPFS sink browser test write failed', error,);
+            return false;
+          }
+        }
+      }
+      return true;
+    },);
+    expect(allSucceeded,).toBe(true,);
+  });
+});