@monochromatic-dev/module-logger 0.1.0

package/src/sink/record-buffer.unit.test.ts

@@ -0,0 +1,288 @@
+import {
+  describe,
+  expect,
+  it,
+} from '@monochromatic-dev/module-test/ts';
+import { wait, } from '@monochromatic-dev/module-async-time/ts';
+import {
+  _createRecordBuffer as createRecordBuffer,
+  type Level,
+} from '@monochromatic-dev/module-logger';
+
+/**
+ * Builds a capturing backend handoff so a test can assert exactly which
+ * batches left the buffer and in what shape.
+ *
+ * @returns Handoff function plus the captured batch list.
+ */
+function createCapturingFlush(): {
+  readonly batches: string[];
+  readonly onFlush: (batch: string,) => void;
+} {
+  const batches: string[] = [];
+  return {
+    batches,
+    onFlush: function captureBatch(batch: string,): void {
+      batches.push(batch,);
+    },
+  };
+}
+
+/**
+ * Installs a capturing `globalThis.addEventListener` (absent under Node, so
+ * the buffer's lifecycle registration is otherwise a no-op there), restoring
+ * the prior value when the returned guard leaves `using` scope.
+ *
+ * @returns Disposable exposing captured handlers by event type.
+ */
+function installFakeGlobalListeners(): Disposable & {
+  readonly handlers: Map<string, () => void>;
+} {
+  const original = globalThis.addEventListener;
+  const handlers = new Map<string, () => void>();
+  globalThis.addEventListener = (function captureListener(
+    type: string,
+    handler: () => void,
+  ): void {
+    handlers.set(type, handler,);
+  }) as unknown as typeof globalThis.addEventListener;
+  return {
+    handlers,
+    [Symbol.dispose](): void {
+      globalThis.addEventListener = original;
+    },
+  };
+}
+
+/**
+ * Installs a fake `globalThis.document` (absent under Node) whose
+ * `visibilityState` is controllable and whose `addEventListener` captures
+ * handlers, restoring the prior value when the returned guard leaves `using`
+ * scope.
+ *
+ * @returns Disposable exposing captured handlers and mutable visibility.
+ */
+function installFakeDocument(): Disposable & {
+  readonly handlers: Map<string, () => void>;
+  readonly visibility: { state: string; };
+} {
+  const original = globalThis.document;
+  const handlers = new Map<string, () => void>();
+  const visibility = { state: 'visible', };
+  globalThis.document = {
+    addEventListener: function captureListener(
+      type: string,
+      handler: () => void,
+    ): void {
+      handlers.set(type, handler,);
+    },
+    get visibilityState(): string {
+      return visibility.state;
+    },
+  } as unknown as Document;
+  return {
+    handlers,
+    visibility,
+    [Symbol.dispose](): void {
+      globalThis.document = original;
+    },
+  };
+}
+
+/**
+ * Severities the buffer must flush synchronously on `add`.
+ */
+const URGENT_LEVELS: readonly Level[] = ['warn', 'error', 'fatal',];
+
+/**
+ * Severities the buffer must keep buffered on `add`.
+ */
+const ROUTINE_LEVELS: readonly Level[] = ['trace', 'debug', 'info',];
+
+// Serial because the lifecycle tests swap `globalThis` members, and because
+// every buffer registers a process-wide pagehide listener, so a concurrent
+// dispatch could drain a sibling test's buffer mid-assertion.
+await describe({
+  name: createRecordBuffer.name,
+  concurrency: 1,
+  children: [
+    it({
+      name: 'a routine record stays buffered until drain, then leaves verbatim',
+      fn: async () => {
+        const { batches, onFlush, } = createCapturingFlush();
+        const buffer = createRecordBuffer({ onFlush, },);
+
+        buffer.add({ level: 'info', serialized: 'r1', },);
+        expect(batches.length,)
+          .toBe(0,);
+
+        buffer.drain();
+        expect(batches.join('|',),)
+          .toBe('r1',);
+      },
+    },),
+
+    it({
+      name: 'drain joins buffered records with newlines in add order',
+      fn: async () => {
+        const { batches, onFlush, } = createCapturingFlush();
+        const buffer = createRecordBuffer({ onFlush, },);
+
+        buffer.add({ level: 'info', serialized: 'r1', },);
+        buffer.add({ level: 'debug', serialized: 'r2', },);
+        buffer.add({ level: 'trace', serialized: 'r3', },);
+        buffer.drain();
+
+        expect(batches.join('|',),)
+          .toBe('r1\nr2\nr3',);
+      },
+    },),
+
+    ...URGENT_LEVELS.map(function mapUrgent(level,) {
+      return it({
+        name: `a ${level} record flushes itself and everything buffered ahead of it`,
+        fn: async () => {
+          const { batches, onFlush, } = createCapturingFlush();
+          const buffer = createRecordBuffer({ onFlush, },);
+
+          buffer.add({ level: 'info', serialized: 'ahead', },);
+          buffer.add({ level, serialized: 'urgent', },);
+
+          expect(batches.join('|',),)
+            .toBe('ahead\nurgent',);
+        },
+      },);
+    },),
+
+    ...ROUTINE_LEVELS.map(function mapRoutine(level,) {
+      return it({
+        name: `a ${level} record does not flush on add`,
+        fn: async () => {
+          const { batches, onFlush, } = createCapturingFlush();
+          const buffer = createRecordBuffer({ onFlush, },);
+
+          buffer.add({ level, serialized: 'routine', },);
+          expect(batches.length,)
+            .toBe(0,);
+
+          // Leave nothing armed behind for later tests.
+          buffer.drain();
+        },
+      },);
+    },),
+
+    it({
+      name: 'reaching the byte cap flushes synchronously from inside add',
+      fn: async () => {
+        const { batches, onFlush, } = createCapturingFlush();
+        const buffer = createRecordBuffer({ onFlush, },);
+
+        // A single record past the 32 KiB cap leaves immediately on add.
+        buffer.add({ level: 'info', serialized: 'L'.repeat(40_000,), },);
+        expect(batches.length,)
+          .toBe(1,);
+      },
+    },),
+
+    it({
+      name: 'an addition that would breach the cap flushes existing entries first',
+      fn: async () => {
+        const { batches, onFlush, } = createCapturingFlush();
+        const buffer = createRecordBuffer({ onFlush, },);
+
+        buffer.add({ level: 'info', serialized: 'small', },);
+        buffer.add({ level: 'info', serialized: 'L'.repeat(40_000,), },);
+
+        // Two separate batches: the small record is never a batch-mate of the
+        // cap-breaching one.
+        expect(batches.length,)
+          .toBe(2,);
+        expect(batches[0],)
+          .toBe('small',);
+      },
+    },),
+
+    it({
+      name: 'the quiet-period deadline drains without any trigger call',
+      fn: async () => {
+        const { batches, onFlush, } = createCapturingFlush();
+        const buffer = createRecordBuffer({ onFlush, },);
+
+        buffer.add({ level: 'debug', serialized: 'idle', },);
+
+        /**
+         * Comfortably past the buffer's 250 ms quiet-period deadline.
+         */
+        const pastDeadlineMs = 400;
+        await wait(pastDeadlineMs,);
+
+        expect(batches.join('|',),)
+          .toBe('idle',);
+      },
+      timeout: 5_000,
+    },),
+
+    it({
+      name: 'drain on an empty buffer is a no-op',
+      fn: async () => {
+        const { batches, onFlush, } = createCapturingFlush();
+        const buffer = createRecordBuffer({ onFlush, },);
+
+        buffer.drain();
+        buffer.drain();
+        expect(batches.length,)
+          .toBe(0,);
+      },
+    },),
+
+    it({
+      name: 'registers a pagehide listener that drains the buffer',
+      fn: async () => {
+        using listeners = installFakeGlobalListeners();
+        const { batches, onFlush, } = createCapturingFlush();
+        const buffer = createRecordBuffer({ onFlush, },);
+
+        buffer.add({ level: 'info', serialized: 'leaving', },);
+        /**
+         * Captured pagehide handler; the buffer must have registered one.
+         */
+        const onPagehide = listeners.handlers
+          .get('pagehide',);
+        expect((typeof onPagehide) === 'function',)
+          .toBe(true,);
+
+        onPagehide?.();
+        expect(batches.join('|',),)
+          .toBe('leaving',);
+      },
+    },),
+
+    it({
+      name: 'registers a visibilitychange listener that drains only when hidden',
+      fn: async () => {
+        using fakeDocument = installFakeDocument();
+        const { batches, onFlush, } = createCapturingFlush();
+        const buffer = createRecordBuffer({ onFlush, },);
+
+        buffer.add({ level: 'info', serialized: 'tabbed away', },);
+        /**
+         * Captured visibilitychange handler; the buffer must have registered one.
+         */
+        const onVisibilityChange = fakeDocument.handlers
+          .get('visibilitychange',);
+        expect((typeof onVisibilityChange) === 'function',)
+          .toBe(true,);
+
+        // Still visible: the handler must not drain.
+        onVisibilityChange?.();
+        expect(batches.length,)
+          .toBe(0,);
+
+        fakeDocument.visibility.state = 'hidden';
+        onVisibilityChange?.();
+        expect(batches.join('|',),)
+          .toBe('tabbed away',);
+      },
+    },),
+  ],
+},);

package/src/sink/session-storage-quota.ts

@@ -0,0 +1,57 @@
+/**
+ * Per-runtime default sessionStorage quota heuristics.
+ *
+ * The Web Storage API exposes no way to read the sessionStorage quota (unlike
+ * `navigator.storage.estimate()`, which reports the unrelated persistent-storage
+ * budget), so the sink caps its own footprint from a table of measured
+ * defaults. Each figure was fill-probed on a fresh store: values are written at
+ * a growing single key until a `QuotaExceededError`, binary-searching the
+ * largest that fits. Figures are UTF-16 code units (JS string length, counting
+ * key plus value) because that is what sessionStorage measures and what the
+ * sink compares `serialized.length` against.
+ *
+ * @module
+ */
+
+import {
+  detectWebStorageRuntime,
+  type WebStorageRuntime,
+} from './web-storage-runtime.ts';
+
+/**
+ * Measured default per-origin sessionStorage quotas, in UTF-16 code units, one
+ * bucket per detectable runtime:
+ *
+ * - `deno`: 10 MiB on Deno 2.9.
+ * - `node`: 5 MiB on Node 26.
+ * - `browser`: 5 MiB, measured identical on Chromium, Firefox, and WebKit under
+ *   Playwright v1.61, so the three engines share one bucket and no fragile
+ *   user-agent sniffing is needed to tell them apart.
+ *
+ * Bun 1.3 exposes no `sessionStorage`, so its bucket is uncapped: its sink
+ * never verifies and never reaches the cap. An unrecognized runtime is also
+ * uncapped so the caller relies on reactive eviction alone.
+ */
+const RUNTIME_QUOTA_CHARS: Record<WebStorageRuntime, number> = {
+  browser: 5_242_880,
+  bun: Number.POSITIVE_INFINITY,
+  deno: 10_485_760,
+  node: 5_242_880,
+  unknown: Number.POSITIVE_INFINITY,
+};
+
+/**
+ * Detects the current runtime's default sessionStorage quota in UTF-16 code
+ * units, or `Number.POSITIVE_INFINITY` when the runtime is unrecognized so the
+ * caller leaves its footprint uncapped and relies on reactive eviction alone.
+ *
+ * @returns Total quota in code units, or `Number.POSITIVE_INFINITY` if unknown.
+ *
+ * @example
+ * ```ts
+ * const capChars = detectSessionStorageQuotaChars() / 2; // half the total
+ * ```
+ */
+export function detectSessionStorageQuotaChars(): number {
+  return RUNTIME_QUOTA_CHARS[detectWebStorageRuntime()];
+}

package/src/sink/session-storage-quota.unit.test.ts

@@ -0,0 +1,98 @@
+import {
+  describe,
+  expect,
+  it,
+} from '@monochromatic-dev/module-test/ts';
+import {
+  _detectSessionStorageQuotaChars as detectSessionStorageQuotaChars,
+} from '@monochromatic-dev/module-logger';
+
+/**
+ * Temporarily sets `globalThis` keys to the supplied values, restoring each to
+ * its prior value (or deleting keys that were absent) when the returned guard
+ * leaves `using` scope, so a runtime-detection test can impersonate Deno, Bun,
+ * or a browser without leaking the fake globals into later tests.
+ *
+ * @param overrides - Global keys to install for the duration of the scope.
+ *
+ * @returns Disposable that restores the original globals on exit.
+ */
+function withGlobalOverrides(overrides: Record<string, unknown>,): Disposable {
+  const host = globalThis as unknown as Record<string, unknown>;
+  const saved = Object.entries(overrides,)
+    .map(function captureAndSet([key, value,],) {
+      const had = key in host;
+      const prior = host[key];
+      host[key] = value;
+      return {
+        key,
+        had,
+        prior,
+      };
+    },);
+  return {
+    [Symbol.dispose](): void {
+      for (const { key, had, prior, } of saved) {
+        if (had)
+          host[key] = prior;
+        else
+          // `delete host[key]` (dynamic key) is banned; this removes the key so
+          // an absent-before global (e.g. `Deno`) does not leak into later tests.
+          Reflect.deleteProperty(host, key,);
+      }
+    },
+  };
+}
+
+await describe({
+  name: detectSessionStorageQuotaChars.name,
+  // Serial because every test mutates process-global runtime markers.
+  concurrency: 1,
+  children: [
+    it({
+      name: 'reads node web storage as 5 MiB',
+      fn: async () => {
+        expect(detectSessionStorageQuotaChars(),)
+          .toBe(5_242_880,);
+      },
+    },),
+
+    it({
+      name: 'reads Deno web storage as 10 MiB',
+      fn: async () => {
+        using _override = withGlobalOverrides({ Deno: {}, },);
+        expect(detectSessionStorageQuotaChars(),)
+          .toBe(10_485_760,);
+      },
+    },),
+
+    it({
+      name: 'leaves Bun uncapped since it exposes no sessionStorage',
+      fn: async () => {
+        using _override = withGlobalOverrides({ Bun: {}, },);
+        expect(detectSessionStorageQuotaChars(),)
+          .toBe(Number.POSITIVE_INFINITY,);
+      },
+    },),
+
+    it({
+      name: 'reads a browser engine as 5 MiB',
+      fn: async () => {
+        // No node markers, but a DOM: the browser bucket, shared by Chromium,
+        // Firefox, and WebKit.
+        using _override = withGlobalOverrides({ process: undefined, document: {}, },);
+        expect(detectSessionStorageQuotaChars(),)
+          .toBe(5_242_880,);
+      },
+    },),
+
+    it({
+      name: 'leaves an unrecognized runtime uncapped',
+      fn: async () => {
+        using _override = withGlobalOverrides({ process: undefined, },);
+        expect(detectSessionStorageQuotaChars(),)
+          .toBe(Number.POSITIVE_INFINITY,);
+      },
+    },),
+  ],
+},);

package/src/sink/session-storage-store.ts

@@ -0,0 +1,178 @@
+import { reportLoggerInternalError, } from '../error-format.ts';
+import { detectSessionStorageQuotaChars, } from './session-storage-quota.ts';
+import { isQuotaExceededError, } from './web-storage-quota-error.ts';
+
+/**
+ * Prefix for sessionStorage keys to namespace log entries.
+ */
+const STORAGE_KEY_PREFIX = 'monochromatic.log';
+
+/**
+ * Builds the namespaced sessionStorage key for a log entry at `index`.
+ *
+ * @param index - Zero-based slot number of an entry.
+ *
+ * @returns Prefixed key such as `monochromatic.log.3`.
+ *
+ * @example
+ * ```ts
+ * storageKey(3); // 'monochromatic.log.3'
+ * ```
+ */
+function storageKey(index: number,): string {
+  return `${STORAGE_KEY_PREFIX}.${index}`;
+}
+
+/**
+ * Builds the persistence engine behind the sessionStorage sink: each `persist`
+ * lands one already-serialized batch under a counter-incremented key, with
+ * proactive and reactive quota eviction. The counter lives in this instance's
+ * closure (no module-global state), so independent sinks and tests never share
+ * keys or need a reset hook.
+ *
+ * The engine caps its own footprint at half the runtime's sessionStorage
+ * quota, proactively dropping its oldest entries, and reactively drops them
+ * again if the real store overflows; see {@link createSessionStorageStore.persist}.
+ *
+ * @returns Engine exposing `persist` for one batch value per call.
+ *
+ * @example
+ * ```ts
+ * const store = createSessionStorageStore();
+ * store.persist('{"level":"info","message":"hi","timestamp":0}');
+ * ```
+ */
+export function createSessionStorageStore(): { readonly persist: (batch: string,) => void; } {
+  /**
+   * Instance-local write cursor, eviction watermark, and footprint tally.
+   * `lineCounter` is the next slot to write and advances only when a `setItem`
+   * actually lands, so this engine's present entries occupy the contiguous
+   * range `[oldestIndex, lineCounter)`. `oldestIndex` is the lowest slot the
+   * engine still owns; eviction removes that entry and climbs `oldestIndex`
+   * toward `lineCounter`, so `oldestIndex < lineCounter` doubles as the "a
+   * prior write succeeded and an owned entry remains" guard that keeps
+   * eviction from ever touching another origin consumer's keys. `usedChars`
+   * tracks the code units this engine currently occupies so the half-quota cap
+   * needs no re-summing. `reportedFailure` gates the give-up diagnostic to
+   * once per failure episode: a persistently full store (another writer owning
+   * the space) would otherwise emit one `console.warn` per batch, so the flag
+   * stays set until a write next lands, which re-arms a single report for the
+   * next episode.
+   */
+  const state: {
+    lineCounter: number;
+    oldestIndex: number;
+    usedChars: number;
+    reportedFailure: boolean;
+  } = {
+    lineCounter: 0,
+    oldestIndex: 0,
+    usedChars: 0,
+    reportedFailure: false,
+  };
+
+  /**
+   * Half the detected runtime sessionStorage quota, in UTF-16 code units, or
+   * `Number.POSITIVE_INFINITY` on an unrecognized runtime. The engine keeps
+   * its own footprint at or below this so the logger never claims more than
+   * half the store, leaving the rest for the host application. An infinite cap
+   * disables the proactive check, leaving only reactive quota-error eviction.
+   */
+  const capChars = detectSessionStorageQuotaChars() / 2;
+
+  /**
+   * Removes this engine's oldest still-present entry, advancing the watermark
+   * and subtracting the reclaimed entry's code units from the running
+   * footprint. Reading the value back before removal keeps `usedChars` honest
+   * even if the entry drifted from what was written.
+   */
+  function evictOldest(): void {
+    /**
+     * Key of the oldest owned entry, removed to reclaim its slot and its space.
+     */
+    const key = storageKey(state.oldestIndex,);
+    /**
+     * Value being evicted, read back so its length can leave the footprint tally.
+     */
+    const evicted = globalThis.sessionStorage
+      .getItem(key,);
+    globalThis.sessionStorage
+      .removeItem(key,);
+    state.oldestIndex++;
+    if (evicted !== null)
+      state.usedChars = Math.max(
+        0,
+        state.usedChars - evicted.length,
+      );
+  }
+
+  /**
+   * Persists one serialized batch to sessionStorage under a
+   * counter-incremented key.
+   *
+   * First it proactively drops its own oldest entries so its footprint stays
+   * at or below half the runtime's sessionStorage quota, leaving the rest for
+   * the host application. It then writes, and on a quota overflow (the store
+   * being fuller than the cap accounts for), and only while an owned entry
+   * remains (so the reclaimed keys are its own, never another origin
+   * consumer's), it drops its oldest still-present entry and retries until the
+   * batch fits or nothing of its own remains to drop. A batch larger than the
+   * whole quota therefore evicts every owned entry, then reports and gives up
+   * rather than looping forever. A non-quota failure is reported without any
+   * eviction. The sink only persists after verification, so no availability
+   * guard is needed here.
+   *
+   * @param batch - Serialized JSONL batch to persist.
+   */
+  function persist(batch: string,): void {
+    /**
+     * Code units this batch adds; the key's length is left out as a negligible near-constant.
+     */
+    const batchChars = batch.length;
+
+    // Proactively reclaim space so the engine's own footprint stays under the
+    // half-quota cap, dropping oldest-first while an owned entry remains. An
+    // infinite cap (unrecognized runtime) makes the guard always false.
+    while ((state.oldestIndex < state.lineCounter) && ((state.usedChars + batchChars) > capChars)) {
+      evictOldest();
+    }
+
+    /**
+     * Write-attempt bound: one try for each entry still available to evict,
+     * followed by one final try after every owned entry has been removed.
+     */
+    const maxWriteAttempts = (state.lineCounter - state.oldestIndex) + 1;
+    for (let writeAttempt = 0; writeAttempt < maxWriteAttempts; writeAttempt++) {
+      try {
+        globalThis.sessionStorage
+          .setItem(
+          storageKey(state.lineCounter,),
+          batch,
+        );
+        state.lineCounter++;
+        state.usedChars += batchChars;
+        // A landed write re-arms a single give-up report for the next episode.
+        state.reportedFailure = false;
+        return;
+      }
+      catch (error: unknown) {
+        if (isQuotaExceededError(error,) && (state.oldestIndex < state.lineCounter)) {
+          evictOldest();
+          continue;
+        }
+        // Report once per failure episode, not once per unwritable batch, so a
+        // persistently full store does not flood the console every flush.
+        if (!state.reportedFailure) {
+          reportLoggerInternalError({
+            context: 'sessionStorage sink record write failed (repeats suppressed until a write next succeeds)',
+            error,
+          },);
+          state.reportedFailure = true;
+        }
+        return;
+      }
+    }
+  }
+
+  return { persist, };
+}