@monochromatic-dev/module-logger 0.1.0

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

@@ -0,0 +1,368 @@
+import { reportLoggerInternalError, } from '../error-format.ts';
+import {
+  buildLogKey,
+  compareLogKeys,
+  parseLogKey,
+  type ParsedLogKey,
+} from './local-storage-key.ts';
+import { detectLocalStorageQuotaChars, } from './local-storage-quota.ts';
+import { isQuotaExceededError, } from './web-storage-quota-error.ts';
+
+/**
+ * Radix for the run nonce so `Number.prototype.toString` yields compact
+ * alphanumerics.
+ */
+const NONCE_RADIX = 36;
+
+/**
+ * Length of the run nonce; four base-36 characters make a same-millisecond
+ * collision between two tabs vanishingly unlikely while keeping keys short.
+ */
+const NONCE_LENGTH = 4;
+
+/**
+ * One adopted prior-run entry: its parsed identity plus the value length it
+ * occupies, captured once at adoption so eviction needs no re-read.
+ */
+type PriorEntry = ParsedLogKey & { readonly chars: number; };
+
+/**
+ * Builds the persistence engine behind the localStorage sink: each `persist`
+ * lands one already-serialized batch under a run-scoped counter-incremented
+ * key, with proactive and reactive quota eviction. Run identity and counters
+ * live in this instance's closure (no module-global state), so independent
+ * sinks and tests never share keys or need a reset hook.
+ *
+ * Unlike sessionStorage, localStorage is shared by every tab of the origin and
+ * survives restarts, so this engine differs from the sessionStorage engine in
+ * two ways. Keys carry a run identity (see `local-storage-key.ts`), so
+ * concurrent tabs never collide on a counter. And on its first persist the
+ * engine adopts every strictly-parsed entry left by other runs into its
+ * footprint tally, evicting those oldest-first before its own entries;
+ * without that, leftovers from dead sessions would fill the store until no
+ * run could ever write again. Adoption is deferred to first persist rather
+ * than construction so building the default sink set never touches
+ * `globalThis.localStorage` on runtimes where the sink never verifies (plain
+ * Node warns on mere access). Keys that fail the strict parse, including the
+ * host application's, are never counted and never evicted.
+ *
+ * The engine caps its own footprint (adopted entries included) at half the
+ * runtime's localStorage quota, proactively dropping oldest-first, and
+ * reactively drops again if the real store still overflows; see
+ * {@link createLocalStorageStore.persist}.
+ *
+ * @returns Engine exposing `persist` for one batch value per call.
+ *
+ * @example
+ * ```ts
+ * const store = createLocalStorageStore();
+ * store.persist('{"level":"info","message":"hi","timestamp":0}');
+ * ```
+ */
+export function createLocalStorageStore(): { readonly persist: (batch: string,) => void; } {
+  /**
+   * Identity of this run, embedded in every key this engine writes: the stamp
+   * orders runs for cross-run eviction and the nonce keeps two tabs started
+   * in the same millisecond apart.
+   */
+  const runIdentity = {
+    stamp: Date.now(),
+    nonce: Math.random()
+      .toString(NONCE_RADIX,)
+      .slice(
+        2,
+        2 + NONCE_LENGTH,
+      )
+      .padEnd(
+        NONCE_LENGTH,
+        '0',
+      ),
+  };
+
+  /**
+   * Instance-local write cursor, eviction watermark, and footprint tally,
+   * mirroring the sessionStorage engine: this run's own entries occupy the
+   * contiguous index range `[oldestIndex, lineCounter)` and `usedChars`
+   * tracks the code units the engine accounts for (adopted prior-run entries
+   * included) so the half-quota cap needs no re-summing. `reportedFailure`
+   * gates the give-up diagnostic to once per failure episode, re-armed by the
+   * next landed write. `adoptedPrior` defers the prior-run scan to the first
+   * persist, which only happens after verification.
+   */
+  const state: {
+    lineCounter: number;
+    oldestIndex: number;
+    usedChars: number;
+    reportedFailure: boolean;
+    adoptedPrior: boolean;
+  } = {
+    lineCounter: 0,
+    oldestIndex: 0,
+    usedChars: 0,
+    reportedFailure: false,
+    adoptedPrior: false,
+  };
+
+  /**
+   * Prior-run entries adopted at first persist, sorted oldest-first, with a
+   * cursor marking how far eviction has consumed them; entries before the
+   * cursor are already removed. Prior entries always evict before this run's
+   * own, since they predate everything this run writes.
+   */
+  const prior: {
+    entries: readonly PriorEntry[];
+    cursor: number;
+  } = {
+    entries: [],
+    cursor: 0,
+  };
+
+  /**
+   * Half the detected runtime localStorage quota, in UTF-16 code units, or
+   * `Number.POSITIVE_INFINITY` on an unrecognized runtime. The engine keeps
+   * its accounted 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 = detectLocalStorageQuotaChars() / 2;
+
+  /**
+   * Builds this run's key for a batch slot.
+   *
+   * @param index - Zero-based batch slot within this run.
+   *
+   * @returns Run-scoped namespaced key.
+   */
+  function ownKey(index: number,): string {
+    return buildLogKey({
+      stamp: runIdentity.stamp,
+      nonce: runIdentity.nonce,
+      index,
+    },);
+  }
+
+  /**
+   * Scans localStorage once for strictly-parsed entries left by other runs,
+   * sorts them oldest-first for eviction, and adds their lengths to the
+   * footprint tally. Entries another tab writes after this scan are invisible
+   * to the tally; the reactive quota loop covers that staleness.
+   */
+  function adoptPriorEntries(): void {
+    /**
+     * Entry count at scan time; enumeration is by index because `Storage`
+     * exposes no iterator.
+     */
+    const total = globalThis.localStorage
+      .length;
+    /**
+     * Strictly-parsed foreign-run entries found by the scan, unsorted.
+     */
+    const found: PriorEntry[] = [];
+    for (let slot = 0; slot < total; slot++) {
+      /**
+       * Key at this enumeration slot; `null` past the end under concurrent removal.
+       */
+      const key = globalThis.localStorage
+        .key(slot,);
+      if (key === null)
+        continue;
+      /**
+       * Parsed run identity, absent for any key the engine must not touch.
+       */
+      const { parsed, } = parseLogKey(key,);
+      if (parsed === undefined)
+        continue;
+      if ((parsed.stamp === runIdentity.stamp) && (parsed.nonce === runIdentity.nonce))
+        continue;
+      /**
+       * Stored batch, read so its length enters the footprint tally.
+       */
+      const value = globalThis.localStorage
+        .getItem(key,);
+      if (value === null)
+        continue;
+      found.push({
+        ...parsed,
+        chars: value.length,
+      },);
+    }
+    prior.entries = found.toSorted(function byOldestFirst(
+      first,
+      second,
+    ) {
+      return compareLogKeys({
+        first,
+        second,
+      },);
+    },);
+    state.usedChars += found.reduce(
+      function sumChars(
+        sum,
+        entry,
+      ) {
+        return sum + entry.chars;
+      },
+      0,
+    );
+  }
+
+  /**
+   * Reports whether anything remains this engine may evict: an adopted
+   * prior-run entry past the cursor, or one of this run's own entries.
+   *
+   * @returns Whether an eviction call would reclaim something.
+   */
+  function hasEvictable(): boolean {
+    /**
+     * Count of adopted prior-run entries; those before the cursor are gone.
+     */
+    const priorCount = prior.entries
+      .length;
+    return (prior.cursor < priorCount)
+      || (state.oldestIndex < state.lineCounter);
+  }
+
+  /**
+   * Removes the oldest not-yet-evicted adopted prior-run entry, if one
+   * remains. Its length leaves the tally from the adoption snapshot: prior
+   * keys are never rewritten (counters only advance), so a re-read could only
+   * observe the same value or a concurrent removal, and in both cases the
+   * snapshot is what the tally counted.
+   *
+   * @returns Whether a prior-run entry was evicted.
+   */
+  function evictOldestPrior(): boolean {
+    /**
+     * Oldest remaining adopted entry, or `undefined` when all are consumed.
+     */
+    const entry = prior.entries[prior.cursor];
+    if (entry === undefined)
+      return false;
+    prior.cursor++;
+    globalThis.localStorage
+      .removeItem(entry.key,);
+    state.usedChars = Math.max(
+      0,
+      state.usedChars - entry.chars,
+    );
+    return true;
+  }
+
+  /**
+   * Removes this run'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 evictOldestOwn(): void {
+    /**
+     * Key of the oldest owned entry, removed to reclaim its slot and its space.
+     */
+    const key = ownKey(state.oldestIndex,);
+    /**
+     * Value being evicted, read back so its length can leave the footprint tally.
+     */
+    const evicted = globalThis.localStorage
+      .getItem(key,);
+    globalThis.localStorage
+      .removeItem(key,);
+    state.oldestIndex++;
+    if (evicted !== null)
+      state.usedChars = Math.max(
+        0,
+        state.usedChars - evicted.length,
+      );
+  }
+
+  /**
+   * Evicts the single oldest thing the engine still owns: adopted prior-run
+   * entries first (they predate everything this run wrote), then this run's
+   * own oldest. Callers guard with {@link hasEvictable}.
+   */
+  function evictOldest(): void {
+    if (evictOldestPrior())
+      return;
+    if (state.oldestIndex < state.lineCounter)
+      evictOldestOwn();
+  }
+
+  /**
+   * Persists one serialized batch to localStorage under this run's next
+   * counter-incremented key.
+   *
+   * The first call adopts prior-run entries into the footprint tally. Each
+   * call then proactively evicts oldest-first (prior runs before this run's
+   * own) until the accounted footprint fits under half the runtime's
+   * localStorage quota, writes, and on a quota overflow (the store being
+   * fuller than the tally accounts for, such as another live tab writing
+   * concurrently) evicts and retries until the batch fits or nothing owned
+   * remains to drop. A batch larger than the whole quota therefore evicts
+   * everything owned, 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 {
+    if (!state.adoptedPrior) {
+      state.adoptedPrior = true;
+      adoptPriorEntries();
+    }
+
+    /**
+     * 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 accounted footprint stays under the
+    // half-quota cap, dropping oldest-first while anything owned remains. An
+    // infinite cap (unrecognized runtime) makes the guard always false.
+    while (hasEvictable() && ((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 = (prior
+      .entries
+      .length
+      - prior.cursor)
+      + (state.lineCounter - state.oldestIndex)
+      + 1;
+    for (let writeAttempt = 0; writeAttempt < maxWriteAttempts; writeAttempt++) {
+      try {
+        globalThis.localStorage
+          .setItem(
+          ownKey(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,) && hasEvictable()) {
+          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: 'localStorage sink record write failed (repeats suppressed until a write next succeeds)',
+            error,
+          },);
+          state.reportedFailure = true;
+        }
+        return;
+      }
+    }
+  }
+
+  return { persist, };
+}

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

@@ -0,0 +1,329 @@
+import {
+  describe,
+  expect,
+  it,
+} from '@monochromatic-dev/module-test/ts';
+import {
+  _createLocalStorageStore as createLocalStorageStore,
+  _parseLogKey as parseLogKey,
+} from '@monochromatic-dev/module-logger';
+
+/**
+ * One mebibyte of UTF-16 code units; the node cap under test is half the
+ * measured 5 MiB quota, so multi-mebibyte batches drive eviction.
+ */
+const MIB = 1_048_576;
+
+/**
+ * Installs `fake` as `globalThis.localStorage` via the property descriptor
+ * (plain assignment would call Node's phantom setter-less path on some hosts),
+ * 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,);
+    },
+  };
+}
+
+/**
+ * Builds an in-memory `Storage` stand-in with full enumeration support (the
+ * engine's adoption scan walks `length`/`key`), rejecting a `setItem` once
+ * stored value lengths would exceed `quotaChars`, throwing the same
+ * `QuotaExceededError` a real backend raises. Records every `removeItem`
+ * under `removed` so a test can assert exactly which keys were evicted.
+ *
+ * @param quotaChars - Total value length the store accepts before
+ * overflowing; omitted means unlimited.
+ *
+ * @returns Storage stand-in exposing `removed` and the raw `backing` map.
+ */
+function createFakeStorage(
+  { quotaChars, }: { readonly quotaChars?: number; } = {},
+): Storage & {
+  readonly backing: Map<string, string>;
+  readonly removed: string[];
+} {
+  const backing = new Map<string, string>();
+  const removed: string[] = [];
+  const used = { chars: 0, };
+  return {
+    backing,
+    removed,
+    get length() {
+      return backing.size;
+    },
+    key(slot: number,) {
+      return [...backing.keys(),][slot] ?? null;
+    },
+    clear(): void {
+      backing.clear();
+      used.chars = 0;
+    },
+    getItem(key: string,) {
+      return backing.get(key,) ?? null;
+    },
+    setItem(key: string, value: string,): void {
+      const priorLength = backing.get(key,)?.length ?? 0;
+      const nextChars = (used.chars - priorLength) + value.length;
+      if ((quotaChars !== undefined) && (nextChars > quotaChars))
+        throw new DOMException('exceeded the quota', 'QuotaExceededError',);
+      backing.set(key, value,);
+      used.chars = nextChars;
+    },
+    removeItem(key: string,): void {
+      removed.push(key,);
+      const priorLength = backing.get(key,)?.length ?? 0;
+      if (backing.delete(key,))
+        used.chars -= priorLength;
+    },
+  } as unknown as Storage & {
+    readonly backing: Map<string, string>;
+    readonly removed: string[];
+  };
+}
+
+/**
+ * Builds an in-memory `Storage` stand-in whose first `setItem` succeeds and
+ * every later one throws a non-quota error, so a test can prove the engine
+ * does not evict for failures other than a quota overflow. Enumeration is
+ * supported for the adoption scan; `removeItem` calls land in `removed`.
+ *
+ * @returns Storage stand-in exposing the evicted-key log as `removed`.
+ */
+function createFlakyStorage(): Storage & { readonly removed: string[]; } {
+  const backing = new Map<string, string>();
+  const removed: string[] = [];
+  const calls = { setItem: 0, };
+  return {
+    removed,
+    get length() {
+      return backing.size;
+    },
+    key(slot: number,) {
+      return [...backing.keys(),][slot] ?? null;
+    },
+    getItem(key: string,) {
+      return backing.get(key,) ?? null;
+    },
+    setItem(key: string, value: string,): void {
+      calls.setItem += 1;
+      if (calls.setItem > 1)
+        throw new Error('localStorage disabled mid-session',);
+      backing.set(key, value,);
+    },
+    removeItem(key: string,): void {
+      removed.push(key,);
+      backing.delete(key,);
+    },
+  } as unknown as Storage & { readonly removed: string[]; };
+}
+
+/**
+ * Captures `console.warn` output, restoring the real method when the returned
+ * guard leaves `using` scope, so a test can count the engine's give-up
+ * reports.
+ *
+ * @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 every test swaps the process-global `localStorage`.
+await describe({
+  name: createLocalStorageStore.name,
+  concurrency: 1,
+  children: [
+    it({
+      name: 'persists batches under run-scoped counter keys',
+      fn: async () => {
+        const fake = createFakeStorage();
+        using _storage = installFakeLocalStorage(fake,);
+        const store = createLocalStorageStore();
+
+        store.persist('alpha',);
+        store.persist('beta',);
+
+        /**
+         * Parsed identities of every landed key; both must carry one shared run identity.
+         */
+        const parsed = [...fake.backing.keys(),]
+          .flatMap((key,) => {
+            const { parsed: identity, } = parseLogKey(key,);
+            return (identity === undefined) ? [] : [identity,];
+          },);
+        expect(parsed,)
+          .toHaveLength(2,);
+        expect(parsed[1]?.stamp,)
+          .toBe(parsed[0]?.stamp,);
+        expect(parsed[1]?.nonce,)
+          .toBe(parsed[0]?.nonce,);
+        expect(parsed.map((identity,) => identity.index,),)
+          .toEqual([0, 1,],);
+        expect(parsed.flatMap((identity,) => fake.backing.get(identity.key,) ?? [],),)
+          .toEqual(['alpha', 'beta',],);
+      },
+    },),
+
+    it({
+      name: 'adopts prior-run entries and evicts them oldest-first under the cap, skipping foreign keys',
+      fn: async () => {
+        const fake = createFakeStorage();
+        // Two dead-run entries totaling 2 MiB, plus two keys the strict parse
+        // must protect: a host-application key under the prefix and a
+        // malformed run identity.
+        fake.setItem('monochromatic.log.1000.aaaa.0', 'x'.repeat(MIB,),);
+        fake.setItem('monochromatic.log.2000.bbbb.0', 'x'.repeat(MIB,),);
+        fake.setItem('monochromatic.log.legacy-note', 'host data',);
+        fake.setItem('monochromatic.log.3000.cccc.nan', 'malformed',);
+        using _storage = installFakeLocalStorage(fake,);
+        const store = createLocalStorageStore();
+
+        // Adopted 2 MiB plus this 1 MiB batch exceeds the 2.5 MiB node cap,
+        // so exactly the oldest dead-run entry must fall.
+        store.persist('y'.repeat(MIB,),);
+
+        expect(fake.removed,)
+          .toEqual(['monochromatic.log.1000.aaaa.0',],);
+        expect(fake.backing.has('monochromatic.log.2000.bbbb.0',),)
+          .toBe(true,);
+        expect(fake.backing.get('monochromatic.log.legacy-note',),)
+          .toBe('host data',);
+        expect(fake.backing.get('monochromatic.log.3000.cccc.nan',),)
+          .toBe('malformed',);
+      },
+    },),
+
+    it({
+      name: 'evicts its own oldest batch after prior entries are exhausted',
+      fn: async () => {
+        const fake = createFakeStorage();
+        using _storage = installFakeLocalStorage(fake,);
+        const store = createLocalStorageStore();
+
+        store.persist('a'.repeat(MIB,),);
+        store.persist('b'.repeat(MIB,),);
+        // The third mebibyte breaches the 2.5 MiB cap; with no prior-run
+        // entries, this run's own index 0 is the oldest thing owned.
+        store.persist('c'.repeat(MIB,),);
+
+        expect(fake.removed,)
+          .toHaveLength(1,);
+        /**
+         * Identity of the evicted key; it must be this run's slot zero.
+         */
+        const { parsed: evicted, } = parseLogKey(fake.removed[0] ?? '',);
+        expect(evicted?.index,)
+          .toBe(0,);
+        /**
+         * Indices still present after eviction, in insertion order.
+         */
+        const remaining = [...fake.backing.keys(),]
+          .flatMap((key,) => {
+            const { parsed: identity, } = parseLogKey(key,);
+            return (identity === undefined) ? [] : [identity.index,];
+          },);
+        expect(remaining,)
+          .toEqual([1, 2,],);
+      },
+    },),
+
+    it({
+      name: 'reactively evicts on a quota overflow the tally did not predict',
+      fn: async () => {
+        // Real capacity far below the runtime cap heuristic, as when another
+        // tab's writes fill space this engine's tally never saw.
+        const fake = createFakeStorage({ quotaChars: 1_500_000, },);
+        fake.setItem('monochromatic.log.1000.aaaa.0', 'x'.repeat(500_000,),);
+        using _storage = installFakeLocalStorage(fake,);
+        const store = createLocalStorageStore();
+
+        // 500k adopted + 1.2M batch fits the 2.5 MiB cap, so no proactive
+        // eviction; the fake's 1.5M quota rejects the write, and the retry
+        // loop must reclaim the dead-run entry.
+        store.persist('z'.repeat(1_200_000,),);
+
+        expect(fake.removed,)
+          .toEqual(['monochromatic.log.1000.aaaa.0',],);
+        /**
+         * Landed batch values after the retry; only the new batch remains.
+         */
+        const values = [...fake.backing.values(),];
+        expect(values,)
+          .toHaveLength(1,);
+        expect(values[0]?.length,)
+          .toBe(1_200_000,);
+      },
+    },),
+
+    it({
+      name: 'reports giving up once per episode and re-arms after a landed write',
+      fn: async () => {
+        const fake = createFakeStorage({ quotaChars: 100, },);
+        using _storage = installFakeLocalStorage(fake,);
+        using warnSpy = spyConsoleWarn();
+        const store = createLocalStorageStore();
+
+        store.persist('a'.repeat(50,),);
+        // Evicts the landed batch, still cannot fit, reports once.
+        store.persist('b'.repeat(200,),);
+        // Same episode: no second report.
+        store.persist('c'.repeat(200,),);
+        expect(warnSpy.calls,)
+          .toHaveLength(1,);
+        expect(warnSpy.calls[0],)
+          .toContain('localStorage sink record write failed',);
+
+        // A landed write re-arms the report for the next episode.
+        store.persist('d'.repeat(30,),);
+        store.persist('e'.repeat(200,),);
+        expect(warnSpy.calls,)
+          .toHaveLength(2,);
+      },
+    },),
+
+    it({
+      name: 'a non-quota failure reports without evicting anything',
+      fn: async () => {
+        const fake = createFlakyStorage();
+        using _storage = installFakeLocalStorage(fake,);
+        using warnSpy = spyConsoleWarn();
+        const store = createLocalStorageStore();
+
+        store.persist('one',);
+        store.persist('two',);
+
+        expect(fake.removed,)
+          .toHaveLength(0,);
+        expect(warnSpy.calls,)
+          .toHaveLength(1,);
+      },
+    },),
+  ],
+},);