@monochromatic-dev/module-logger 0.1.0

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

@@ -0,0 +1,176 @@
+/**
+ * Key naming for the localStorage persistence engine.
+ *
+ * localStorage is shared by every tab of the origin and survives restarts, so
+ * unlike the per-tab sessionStorage keys (`monochromatic.log.{n}`), these keys
+ * carry a run identity: `monochromatic.log.{stamp}.{nonce}.{index}`. The stamp
+ * orders runs oldest-first for cross-run eviction, the nonce keeps two tabs
+ * started in the same millisecond from colliding, and the index orders batches
+ * within a run.
+ *
+ * @module
+ */
+
+/**
+ * Prefix namespacing this logger's localStorage entries away from host
+ * application keys.
+ */
+export const LOCAL_STORAGE_KEY_PREFIX = 'monochromatic.log';
+
+/**
+ * Identity segments after the prefix: stamp, nonce, and index.
+ */
+const RUN_KEY_SEGMENTS = 3;
+
+/**
+ * Parsed identity of one owned localStorage entry, used to order eviction
+ * across runs.
+ */
+export type ParsedLogKey = {
+  readonly key: string;
+  readonly stamp: number;
+  readonly nonce: string;
+  readonly index: number;
+};
+
+/**
+ * Reports whether `text` is one or more ASCII digits, so key parsing accepts
+ * only counter-shaped segments and never claims a host application's key. A
+ * linear scan instead of a regex: the rule is a plain character-range check.
+ *
+ * @param text - Candidate key segment.
+ *
+ * @returns Whether every character is an ASCII digit and one exists.
+ */
+function isDigits(text: string,): boolean {
+  if (text.length === 0)
+    return false;
+  for (const character of text) {
+    if ((character < '0') || (character > '9'))
+      return false;
+  }
+  return true;
+}
+
+/**
+ * Builds the namespaced localStorage key for one batch slot of one run.
+ *
+ * @param stamp - Run creation time ordering runs oldest-first.
+ *
+ * @param nonce - Same-millisecond disambiguator between concurrent tabs.
+ *
+ * @param index - Zero-based batch slot within the run.
+ *
+ * @returns Key such as `monochromatic.log.1753000000000.a1b2.3`.
+ *
+ * @example
+ * ```ts
+ * buildLogKey({ stamp: 1753000000000, nonce: 'a1b2', index: 3 });
+ * ```
+ */
+export function buildLogKey(
+  {
+    stamp,
+    nonce,
+    index,
+  }: {
+    readonly stamp: number;
+    readonly nonce: string;
+    readonly index: number;
+  },
+): string {
+  return `${LOCAL_STORAGE_KEY_PREFIX}.${stamp}.${nonce}.${index}`;
+}
+
+/**
+ * Parses a localStorage key back into its run identity, or reports it foreign
+ * by leaving `parsed` absent. Parsing is strict (exact prefix, exactly the
+ * identity segment count, digit-shaped stamp and index, non-empty nonce)
+ * because eviction trusts this to never classify a host application's key, or
+ * the sessionStorage sink's flat `monochromatic.log.{n}` shape, as evictable.
+ *
+ * @param key - Candidate localStorage key.
+ *
+ * @returns Wrapper whose `parsed` property is present only for an owned key.
+ *
+ * @example
+ * ```ts
+ * parseLogKey('monochromatic.log.1753000000000.a1b2.3').parsed; // ParsedLogKey
+ * parseLogKey('monochromatic.log.5').parsed; // undefined: sessionStorage shape
+ * ```
+ */
+export function parseLogKey(key: string,): { readonly parsed?: ParsedLogKey; } {
+  if (!key.startsWith(`${LOCAL_STORAGE_KEY_PREFIX}.`,))
+    return {};
+  /**
+   * Key remainder past the prefix and its trailing dot, holding the run
+   * identity segments.
+   */
+  const rest = key.slice(LOCAL_STORAGE_KEY_PREFIX.length + 1,);
+  /**
+   * Dot-separated identity segments; exactly stamp, nonce, index for an owned
+   * key.
+   */
+  const segments = rest.split('.',);
+  if (segments.length !== RUN_KEY_SEGMENTS)
+    return {};
+  /**
+   * Identity segments in declaration order; any missing or malformed one
+   * makes the key foreign.
+   */
+  const [stampText, nonce, indexText,] = segments;
+  if (
+    (stampText === undefined)
+    || (nonce === undefined)
+      || (indexText === undefined)
+  )
+    return {};
+  if (!isDigits(stampText,))
+    return {};
+  if (nonce.length === 0)
+    return {};
+  if (!isDigits(indexText,))
+    return {};
+  return {
+    parsed: {
+      key,
+      stamp: Math.trunc(Number(stampText,),),
+      nonce,
+      index: Math.trunc(Number(indexText,),),
+    },
+  };
+}
+
+/**
+ * Orders parsed keys oldest-first for eviction: by run stamp, then by nonce
+ * (an arbitrary but stable tiebreak between same-millisecond runs), then by
+ * batch index within the run.
+ *
+ * @param first - Parsed key compared first.
+ *
+ * @param second - Parsed key compared second.
+ *
+ * @returns Negative when `first` is older, positive when newer, zero on ties.
+ *
+ * @example
+ * ```ts
+ * entries.toSorted(function byOldestFirst(first, second) {
+ *   return compareLogKeys({ first, second });
+ * });
+ * ```
+ */
+export function compareLogKeys(
+  {
+    first,
+    second,
+  }: {
+    readonly first: ParsedLogKey;
+    readonly second: ParsedLogKey;
+  },
+): number {
+  if (first.stamp !== second.stamp)
+    return first.stamp - second.stamp;
+  if (first.nonce !== second.nonce)
+    return (first.nonce < second.nonce) ? -1 : 1;
+  return first.index - second.index;
+}

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

@@ -0,0 +1,106 @@
+import {
+  describe,
+  expect,
+  it,
+} from '@monochromatic-dev/module-test/ts';
+import {
+  _buildLogKey as buildLogKey,
+  _compareLogKeys as compareLogKeys,
+  _parseLogKey as parseLogKey,
+} from '@monochromatic-dev/module-logger';
+
+/**
+ * Keys the strict parser must reject: host application keys, the
+ * sessionStorage sink's flat shape, and malformed run identities. Eviction
+ * safety rests on every one of these staying foreign.
+ */
+const FOREIGN_KEYS: readonly string[] = [
+  'other.key',
+  'monochromatic.log',
+  'monochromatic.log.5',
+  'monochromatic.log.10.ab',
+  'monochromatic.log.10.ab.3.4',
+  'monochromatic.log.x10.ab.3',
+  'monochromatic.log.10..3',
+  'monochromatic.log.10.ab.3x',
+  'monochromatic.log...',
+];
+
+await describe({
+  name: parseLogKey.name,
+  children: [
+    it({
+      name: 'round-trips a built key back to its identity',
+      fn: async () => {
+        /**
+         * Identity pushed through build-then-parse; equality proves the pair inverse.
+         */
+        const identity = {
+          stamp: 1_753_000_000_000,
+          nonce: 'ab12',
+          index: 7,
+        };
+        /**
+         * Key the builder produced for the identity.
+         */
+        const built = buildLogKey(identity,);
+        /**
+         * Identity parsed back out of the built key.
+         */
+        const { parsed, } = parseLogKey(built,);
+        expect(parsed,)
+          .toEqual({
+            key: 'monochromatic.log.1753000000000.ab12.7',
+            ...identity,
+          },);
+      },
+    },),
+
+    ...FOREIGN_KEYS.map(function mapForeign(key,) {
+      return it({
+        name: `rejects foreign key ${key}`,
+        fn: async () => {
+          expect(parseLogKey(key,).parsed,)
+            .toBeUndefined();
+        },
+      },);
+    },),
+
+    it({
+      name: 'compareLogKeys orders by stamp, then nonce, then index',
+      fn: async () => {
+        /**
+         * Keys deliberately shuffled across all three ordering dimensions.
+         */
+        const shuffled = [
+          'monochromatic.log.2000.aaaa.0',
+          'monochromatic.log.1000.bbbb.1',
+          'monochromatic.log.1000.aaaa.1',
+          'monochromatic.log.1000.aaaa.0',
+        ]
+          .flatMap(function parseOne(key,) {
+            const { parsed, } = parseLogKey(key,);
+            return (parsed === undefined) ? [] : [parsed,];
+          },);
+        /**
+         * Oldest-first ordering the eviction queue relies on.
+         */
+        const sorted = shuffled.toSorted(function byOldestFirst(first, second,) {
+          return compareLogKeys({
+            first,
+            second,
+          },);
+        },);
+        expect(sorted.map(function keyOf(parsed,) {
+          return parsed.key;
+        },),)
+          .toEqual([
+            'monochromatic.log.1000.aaaa.0',
+            'monochromatic.log.1000.aaaa.1',
+            'monochromatic.log.1000.bbbb.1',
+            'monochromatic.log.2000.aaaa.0',
+          ],);
+      },
+    },),
+  ],
+},);

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

@@ -0,0 +1,60 @@
+/**
+ * Per-runtime default localStorage quota heuristics.
+ *
+ * The Web Storage API exposes no way to read the localStorage 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 localStorage measures and what the sink
+ * compares `serialized.length` against.
+ *
+ * @module
+ */
+
+import {
+  detectWebStorageRuntime,
+  type WebStorageRuntime,
+} from './web-storage-runtime.ts';
+
+/**
+ * Measured default per-origin localStorage quotas, in UTF-16 code units, one
+ * bucket per detectable runtime:
+ *
+ * - `deno`: 10,477,569 on Deno 2.9, which lands 8 KiB short of the 10 MiB its
+ *   sessionStorage measures, presumably backing-store overhead; the measured
+ *   figure is kept as-is rather than rounded up past what actually fits.
+ * - `node`: 5 MiB on Node 26 launched with `--localstorage-file`.
+ * - `browser`: 5 MiB, measured on headless Chromium 149 over an
+ *   `http://127.0.0.1` origin. Firefox and WebKit are assumed to share the
+ *   bucket: both measured 5 MiB for sessionStorage under Playwright v1.61 and
+ *   neither was fill-probed for localStorage here.
+ *
+ * Bun 1.3 exposes no `localStorage`, 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_477_569,
+  node: 5_242_880,
+  unknown: Number.POSITIVE_INFINITY,
+};
+
+/**
+ * Detects the current runtime's default localStorage 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 = detectLocalStorageQuotaChars() / 2; // half the total
+ * ```
+ */
+export function detectLocalStorageQuotaChars(): number {
+  return RUNTIME_QUOTA_CHARS[detectWebStorageRuntime()];
+}

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

@@ -0,0 +1,98 @@
+import {
+  describe,
+  expect,
+  it,
+} from '@monochromatic-dev/module-test/ts';
+import {
+  _detectLocalStorageQuotaChars as detectLocalStorageQuotaChars,
+} 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: detectLocalStorageQuotaChars.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(detectLocalStorageQuotaChars(),)
+          .toBe(5_242_880,);
+      },
+    },),
+
+    it({
+      name: 'reads Deno web storage as its measured just-under-10-MiB figure',
+      fn: async () => {
+        using _override = withGlobalOverrides({ Deno: {}, },);
+        expect(detectLocalStorageQuotaChars(),)
+          .toBe(10_477_569,);
+      },
+    },),
+
+    it({
+      name: 'leaves Bun uncapped since it exposes no localStorage',
+      fn: async () => {
+        using _override = withGlobalOverrides({ Bun: {}, },);
+        expect(detectLocalStorageQuotaChars(),)
+          .toBe(Number.POSITIVE_INFINITY,);
+      },
+    },),
+
+    it({
+      name: 'reads a browser engine as 5 MiB',
+      fn: async () => {
+        // No node markers, but a DOM: the browser bucket, measured on Chromium
+        // and assumed shared by Firefox and WebKit.
+        using _override = withGlobalOverrides({ process: undefined, document: {}, },);
+        expect(detectLocalStorageQuotaChars(),)
+          .toBe(5_242_880,);
+      },
+    },),
+
+    it({
+      name: 'leaves an unrecognized runtime uncapped',
+      fn: async () => {
+        using _override = withGlobalOverrides({ process: undefined, },);
+        expect(detectLocalStorageQuotaChars(),)
+          .toBe(Number.POSITIVE_INFINITY,);
+      },
+    },),
+  ],
+},);