@monochromatic-dev/module-logger 0.1.0

package/src/sink/opfs.ts

@@ -0,0 +1,212 @@
+import { reportLoggerInternalError, } from '../error-format.ts';
+import { createRecordBuffer, } from './record-buffer.ts';
+
+import type {
+  Level,
+  Sink,
+} from '../types.ts';
+
+/**
+ * Builds an OPFS sink that buffers serialized records through the shared
+ * {@link createRecordBuffer} policy and appends each newline-joined JSONL
+ * batch to a per-session file in the Origin Private File System with one
+ * stream write per batch. The kept-open writable stream lives in this
+ * instance's closure (no module-global state), so independent loggers and
+ * tests never share a handle or need a reset hook.
+ *
+ * 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}. Batch writes queue on the stream
+ * in issue order, so ordering holds at the batch boundary, and the sink's
+ * `flush` hook awaits every issued batch before resolving.
+ *
+ * @returns Sink backed by OPFS.
+ *
+ * @example
+ * ```ts
+ * const { logger } = createLogger({ sinks: [createOpfsSink()] });
+ * logger.warn('quota nearing limit');
+ * ```
+ */
+export function createOpfsSink(): Sink {
+  /**
+   * Instance-local kept-open OPFS stream, opened by `verify` and reused by
+   * every batch write. Absent until a successful verification.
+   */
+  const state: { writable?: FileSystemWritableFileStream; } = {};
+
+  /**
+   * Batch writes issued to the stream and not yet settled; the `flush` hook
+   * drains this so logger-level `flush()` observes every issued batch.
+   */
+  const pendingBatchWrites = new Set<Promise<void>>();
+
+  /**
+   * Verifies OPFS is available and round-trips a probe write, then opens the
+   * stream reused by subsequent writes. The logger calls this once and owns
+   * the resulting availability.
+   *
+   * @returns Whether OPFS logging is available.
+   */
+  async function verify(): Promise<boolean> {
+    try {
+      /**
+       * Origin Private File System directory handle that hosts every monochromatic log file.
+       */
+      const opfsRoot = await navigator.storage
+        .getDirectory();
+      /**
+       * ISO timestamp with colons replaced by dashes so it can be embedded in a cross-platform file name.
+       */
+      const timestamp = new Date().toISOString()
+        .replaceAll(
+        ':',
+        '-',
+      );
+      /**
+       * OPFS handle for the per-run log file, created on first verification and reused for subsequent writes.
+       */
+      const fileHandle = await opfsRoot.getFileHandle(
+        `monochromatic-${timestamp}.log.jsonl`,
+        { create: true, },
+      );
+      // Write test data and close to flush; getFile() reads stale content
+      // while a FileSystemWritableFileStream is still open.
+      /**
+       * Throwaway writable used only to flush the probe so the next `getFile` returns persisted content.
+       */
+      const probeWritable = await fileHandle.createWritable({ keepExistingData: true, },);
+      /**
+       * Probe record written and read back to confirm OPFS round-trips writes.
+       */
+      const testData = `{"test":true,"timestamp":${Date.now()}}\n`;
+      await probeWritable.write(testData,);
+      await probeWritable.close();
+
+      /**
+       * File snapshot of the probe, taken after closing `probeWritable` so its bytes are flushed.
+       */
+      const file = await fileHandle.getFile();
+      /**
+       * Probe contents read back; matching the literal `"test":true` proves OPFS persisted the data.
+       */
+      const content = await file.text();
+      /**
+       * Whether the probe round-tripped; only then is the reused stream opened.
+       */
+      const available = content.includes('"test":true',);
+
+      if (available)
+        // Reopen for subsequent log writes.
+        state.writable = await fileHandle.createWritable({ keepExistingData: true, },);
+
+      return available;
+    }
+    catch (error: unknown) {
+      /**
+       * OPFS storage object, present only when the current platform exposes the backend this sink verifies.
+       */
+      const opfsStorage = globalThis.navigator
+        ?.storage;
+      if ((opfsStorage !== undefined) && ('getDirectory' in opfsStorage))
+        reportLoggerInternalError({
+          context: 'OPFS sink verification failed',
+          error,
+        },);
+      return false;
+    }
+  }
+
+  /**
+   * Writes one newline-terminated batch to the OPFS stream, swallowing and
+   * reporting failures so the pending-write set always settles.
+   *
+   * @param batch - Newline-joined JSONL batch from the buffer.
+   */
+  async function writeBatch(batch: string,): Promise<void> {
+    if (!state.writable)
+      return;
+
+    try {
+      await state.writable
+        .write(`${batch}\n`,);
+    }
+    catch (error: unknown) {
+      reportLoggerInternalError({
+        context: 'OPFS sink record write failed',
+        error,
+      },);
+    }
+  }
+
+  /**
+   * Removes a tracked batch write from {@link pendingBatchWrites} once it
+   * settles.
+   *
+   * @param pending - Promise returned by {@link writeBatch}.
+   */
+  async function removePendingWhenSettled(pending: Promise<void>,): Promise<void> {
+    await pending;
+    pendingBatchWrites.delete(pending,);
+  }
+
+  /**
+   * Backend handoff for the buffer: issues the batch write without awaiting
+   * (stream writes queue in issue order) and tracks it for the `flush` hook.
+   *
+   * @param batch - Newline-joined JSONL batch from the buffer.
+   */
+  function handOffBatch(batch: string,): void {
+    /**
+     * In-flight batch write; never rejects, because {@link writeBatch} reports internally.
+     */
+    const pending = writeBatch(batch,);
+    pendingBatchWrites.add(pending,);
+    void removePendingWhenSettled(pending,);
+  }
+
+  /**
+   * Shared buffering stage; every flush trigger issues one queued stream
+   * write per joined batch.
+   */
+  const buffer = createRecordBuffer({ onFlush: handOffBatch, },);
+
+  /**
+   * Buffers a log record through the shared policy; see
+   * {@link createRecordBuffer} for the flush triggers.
+   *
+   * @param record - Log record to buffer and eventually append.
+   *
+   * @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 onto the stream and resolves once every issued batch
+   * write has settled.
+   */
+  async function flush(): Promise<void> {
+    buffer.drain();
+    /**
+     * Snapshot of in-flight batch writes at drain time.
+     */
+    const writes = [...pendingBatchWrites,];
+    await Promise.all(writes,);
+  }
+
+  return {
+    flush,
+    verify,
+    write,
+  };
+}

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

@@ -0,0 +1,81 @@
+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 {
+  createOpfsSink,
+} = sinks;
+
+// Node/Bun has no `navigator.storage`, so this file exercises the
+// unavailable-backend fallback that the browser test (which runs where OPFS
+// exists) never reaches: `getDirectory` throws and is caught, and drained
+// batches hit the unset-stream guard. The available path lives in
+// `opfs.browser.test.ts`; the shared buffering policy is covered in
+// `record-buffer.unit.test.ts`.
+await describe({
+  name: 'OPFS sink (node fallback)',
+  children: [
+    it({
+      name: 'verify resolves false when OPFS is absent',
+      fn: async () => {
+        // `navigator.storage.getDirectory()` dereferences an undefined member
+        // and throws; verify catches it and reports the backend unavailable.
+        const sink = createOpfsSink();
+        expect(await sink.verify(),)
+          .toBe(false,);
+      },
+    },),
+
+    it({
+      name: 'write buffers without throwing when OPFS is absent',
+      fn: async () => {
+        // The record buffers; nothing touches the missing backend until a
+        // flush trigger fires.
+        const sink = createOpfsSink();
+        /**
+         * Resolved write result; the sink write contract is `Promise<void>`.
+         */
+        const result = await sink.write({
+          level: 'info',
+          message: 'dropped',
+          timestamp: 0,
+        },);
+        expect(result,)
+          .toBeUndefined();
+      },
+    },),
+
+    it({
+      name: 'flush drains the buffer into the unset-stream guard and resolves',
+      fn: async () => {
+        // A warn record drains synchronously on add, an info record drains on
+        // the flush hook; both batches hit the guard and are dropped silently.
+        const sink = createOpfsSink();
+        await sink.write({
+          level: 'warn',
+          message: 'urgent but backendless',
+          timestamp: 0,
+        },);
+        await sink.write({
+          level: 'info',
+          message: 'buffered but backendless',
+          timestamp: 1,
+        },);
+        /**
+         * Resolved flush result; must settle even with no stream to write to.
+         */
+        const result = await sink.flush?.();
+        expect(result,)
+          .toBeUndefined();
+      },
+    },),
+  ],
+},);

package/src/sink/record-buffer.ts

@@ -0,0 +1,230 @@
+import type { Level, } from '../types.ts';
+
+/**
+ * Buffered code units that force a synchronous flush from inside `add`
+ * itself. 32 KiB sits in the measured flat bottom of the batch-size curve on
+ * Chromium 149 and Node 26 (0.15 µs to 1.7 µs per record versus 5 µs to
+ * 15 µs unbatched) while staying clear of the measured U-turn where flushes
+ * past ~100 KiB cost more per record than not batching; see
+ * `doc/troubleshooting/web-storage-sink-main-thread-cost.md`. Because this
+ * flush runs synchronously inside `add`, a wedged main thread that keeps
+ * logging can never hold more than one cap's worth of unpersisted records.
+ */
+const FLUSH_BUFFER_CAP_CHARS = 32_768;
+
+/**
+ * Quiet-period deadline before a buffered record is flushed by timer, so
+ * low-volume sessions still reach the backend without waiting for the byte
+ * cap. Each deadline flush costs one backend call, so this cadence is
+ * negligible while keeping the loss window for idle periods under a quarter
+ * second.
+ */
+const FLUSH_DEADLINE_MS = 250;
+
+/**
+ * Severities that flush the buffer synchronously from inside `add`, so every
+ * record up to and including a warning or worse reaches the backend before
+ * control returns to the caller. Failure forensics is why persistent sinks
+ * exist; these records are rare, so paying the per-batch cost immediately
+ * for them does not dent the amortization of the bulk `debug`/`trace`/`info`
+ * volume.
+ */
+const FLUSH_IMMEDIATELY_BY_LEVEL: Record<Level, boolean> = {
+  debug: false,
+  error: true,
+  fatal: true,
+  info: false,
+  trace: false,
+  warn: true,
+};
+
+/**
+ * Timer handle exposing Node's keep-alive release. Browsers return a bare
+ * number from `setTimeout` and need no release; Node returns an object whose
+ * `unref` lets the process exit while the timer is pending.
+ */
+type UnrefableTimer = { readonly unref: () => void; };
+
+/**
+ * Narrows a `setTimeout` return value to a handle exposing `unref`, so a
+ * pending deadline flush never pins a server process open past its work.
+ *
+ * @param timer - Return value of `globalThis.setTimeout`.
+ *
+ * @returns Whether `timer` exposes a callable `unref`.
+ */
+function isUnrefableTimer(timer: unknown,): timer is UnrefableTimer {
+  if (((typeof timer) !== 'object') || (timer === null))
+    return false;
+  if (!('unref' in timer))
+    return false;
+  return (typeof timer.unref) === 'function';
+}
+
+/**
+ * Builds the buffering stage shared by batch-persisting sinks: serialized
+ * records accumulate and leave as one newline-joined JSONL batch through
+ * `onFlush`. One uniform policy runs on every runtime; no per-runtime mode
+ * exists.
+ *
+ * A batch flushes synchronously from inside `add` when it reaches
+ * {@link FLUSH_BUFFER_CAP_CHARS} or when the record's severity is `warn` or
+ * worse, by timer after {@link FLUSH_DEADLINE_MS} of quiet, on `pagehide`
+ * and on the document becoming hidden (where those events exist), and on
+ * `drain`. The byte-cap and severity flushes run on the caller's stack, so
+ * neither a synchronous workload nor a wedged main thread can accumulate
+ * more than one cap of unhanded records. When an addition would breach the
+ * cap, the existing entries flush first so an oversized record's downstream
+ * failure can only ever drop that record, never its batch-mates.
+ *
+ * @param onFlush - Backend handoff receiving each newline-joined batch;
+ * called synchronously from whichever trigger fires, in record order.
+ *
+ * @returns Buffer exposing `add` for records and `drain` for forced flushes.
+ *
+ * @example
+ * ```ts
+ * const buffer = createRecordBuffer({ onFlush: (batch) => store.persist(batch) });
+ * buffer.add({ level: 'info', serialized: JSON.stringify(record) });
+ * buffer.drain();
+ * ```
+ */
+export function createRecordBuffer(
+  { onFlush, }: { readonly onFlush: (batch: string,) => void; },
+): {
+  readonly add: (entry: {
+    readonly level: Level;
+    readonly serialized: string;
+  },) => void;
+  readonly drain: () => void;
+} {
+  /**
+   * Serialized records awaiting one joined handoff; drained in add order by
+   * every flush trigger.
+   */
+  const entries: string[] = [];
+
+  /**
+   * Instance-local buffer bookkeeping. `chars` mirrors the joined length of
+   * {@link entries} (records plus one separator between neighbors) so cap
+   * checks need no re-summing; `timer`, present only while armed, holds the
+   * quiet-period deadline flush so idle sessions still hand off.
+   */
+  const bufferState: {
+    chars: number;
+    timer?: ReturnType<typeof globalThis.setTimeout>;
+  } = { chars: 0, };
+
+  /**
+   * Joined length the buffer would have after appending `serialized`,
+   * counting the newline separator a non-empty buffer needs before it.
+   *
+   * @param serialized - Record about to be appended.
+   *
+   * @returns Prospective joined batch length in code units.
+   */
+  function charsWith(serialized: string,): number {
+    /**
+     * Newline separator the join adds before this record when the buffer already holds one.
+     */
+    const separatorChars = (entries.length > 0) ? 1 : 0;
+    /**
+     * Length of the buffer as currently joined, before this record.
+     */
+    const joinedChars = bufferState.chars + separatorChars;
+    return joinedChars + serialized.length;
+  }
+
+  /**
+   * Hands the buffered records to `onFlush` as one newline-joined batch and
+   * disarms the deadline timer. Runs synchronously so byte-cap and severity
+   * flushes complete on the caller's stack. Safe to call with an empty
+   * buffer.
+   */
+  function drain(): void {
+    if (bufferState.timer !== undefined) {
+      globalThis.clearTimeout(bufferState.timer,);
+      delete bufferState.timer;
+    }
+    if (entries.length === 0)
+      return;
+    /**
+     * Newline-joined JSONL batch; `JSON.stringify` escapes newlines inside
+     * records, so the separator is unambiguous for readers splitting lines.
+     */
+    const batch = entries.join('\n',);
+    entries.length = 0;
+    bufferState.chars = 0;
+    onFlush(batch,);
+  }
+
+  /**
+   * Arms the quiet-period deadline flush if none is pending, releasing the
+   * runtime's keep-alive where the handle supports it so a pending flush
+   * never holds a process open.
+   */
+  function scheduleDeadlineFlush(): void {
+    if (bufferState.timer !== undefined)
+      return;
+    /**
+     * Freshly armed deadline handle; kept on {@link bufferState} so a cap or severity flush can disarm it.
+     */
+    const timer = globalThis.setTimeout(
+      drain,
+      FLUSH_DEADLINE_MS,
+    );
+    if (isUnrefableTimer(timer,))
+      timer.unref();
+    bufferState.timer = timer;
+  }
+
+  /**
+   * Buffers one serialized record, flushing synchronously when the joined
+   * batch reaches the byte cap or the record's severity is `warn` or worse.
+   *
+   * @param entry - Serialized record plus the severity that decides an
+   * immediate flush.
+   */
+  function add(entry: {
+    readonly level: Level;
+    readonly serialized: string;
+  },): void {
+    // Protect batch-mates: an addition that would breach the cap flushes the
+    // current entries first, isolating any oversized record in its own batch.
+    if ((entries.length > 0) && (charsWith(entry.serialized,) > FLUSH_BUFFER_CAP_CHARS))
+      drain();
+
+    bufferState.chars = charsWith(entry.serialized,);
+    entries.push(entry.serialized,);
+
+    if (FLUSH_IMMEDIATELY_BY_LEVEL[entry.level] || (bufferState.chars >= FLUSH_BUFFER_CAP_CHARS))
+      drain();
+    else
+      scheduleDeadlineFlush();
+  }
+
+  // A leaving or hidden page is the last chance to hand off; both hooks are
+  // harmless no-ops on runtimes where the events never fire.
+  globalThis.addEventListener?.(
+    'pagehide',
+    drain,
+  );
+  globalThis.document
+    ?.addEventListener(
+      'visibilitychange',
+      function flushWhenHidden(): void {
+        /**
+         * Current page visibility; the listener only fires where a document exists.
+         */
+        const visibility = globalThis.document
+          ?.visibilityState;
+        if (visibility === 'hidden')
+          drain();
+      },
+    );
+
+  return {
+    add,
+    drain,
+  };
+}