@monochromatic-dev/module-logger 0.1.0

package/src/error-format.ts

@@ -0,0 +1,43 @@
+/**
+ * Internal logger error reporting helpers.
+ *
+ * Logger internals cannot report failures through the logger itself without
+ * risking recursion, so these helpers format caught values and write directly
+ * to the host console.
+ *
+ * @module
+ */
+
+import { caughtValueText, } from '@monochromatic-dev/module-caught-value/ts';
+
+/**
+ * Reports a logger-internal caught value without going back through logger
+ * sinks, formatting it via {@link caughtValueText}.
+ *
+ * @param context - Human-readable operation that caught the value.
+ *
+ * @param error - Caught value to include in the diagnostic.
+ *
+ * @mutates error - `caughtValueText` may invoke string-conversion hooks.
+ *
+ * @example
+ * ```ts
+ * reportLoggerInternalError({
+ *   context: 'console sink verify failed',
+ *   error: new Error('blocked'),
+ * });
+ * ```
+ */
+export function reportLoggerInternalError(
+  {
+    context,
+    error,
+  }: {
+    readonly context: string;
+    readonly error: unknown;
+  },
+): void {
+  console.warn(
+    `logger internal error: ${context}: ${caughtValueText(error,)}`,
+  );
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+export {
+  createLogger,
+  DEFAULT_FLUSH_DEADLINE_MS,
+} from './create-logger.ts';
+export {
+  initPromise,
+  logger,
+} from './logger.ts';
+export * as sinks from './sink/index.ts';
+export { tagged, } from './tagged.ts';
+
+//region Internal seams
+// Underscore-prefixed re-exports let unit tests exercise internal modules
+// through the built artifact (the `require-eventual-artifact` rule) without
+// widening the documented API; they are not part of the public contract.
+export { neutralizeControlCharacters as _neutralizeControlCharacters, } from './sink/console-control-chars.ts';
+export {
+  buildLogKey as _buildLogKey,
+  compareLogKeys as _compareLogKeys,
+  parseLogKey as _parseLogKey,
+} from './sink/local-storage-key.ts';
+export { detectLocalStorageQuotaChars as _detectLocalStorageQuotaChars, } from './sink/local-storage-quota.ts';
+export { createLocalStorageStore as _createLocalStorageStore, } from './sink/local-storage-store.ts';
+export { createRecordBuffer as _createRecordBuffer, } from './sink/record-buffer.ts';
+export { detectSessionStorageQuotaChars as _detectSessionStorageQuotaChars, } from './sink/session-storage-quota.ts';
+export { isQuotaExceededError as _isQuotaExceededError, } from './sink/web-storage-quota-error.ts';
+//endregion Internal seams
+export type {
+  Level,
+  Logger,
+  LogRecord,
+  Sink,
+  SinkFlush,
+  Verify,
+} from './types.ts';

package/src/logger.ts

@@ -0,0 +1,67 @@
+import { createLogger, } from './create-logger.ts';
+import { createConsoleSink, } from './sink/console.ts';
+import { createFileSink, } from './sink/file.ts';
+import { createIndexedDbSink, } from './sink/indexed-db.ts';
+import { createLocalStorageSink, } from './sink/local-storage.ts';
+import { createSessionStorageSink, } from './sink/session-storage.ts';
+import type {
+  Logger,
+  Sink,
+} from './types.ts';
+
+/**
+ * Default sink backends to attempt, in priority order. Each runtime keeps
+ * only the sinks whose `verify` confirms its backend: {@link createConsoleSink}
+ * everywhere, {@link createIndexedDbSink} in browsers,
+ * {@link createSessionStorageSink} wherever web storage round-trips (browsers,
+ * Node 22+, Deno), {@link createLocalStorageSink} wherever `localStorage`
+ * round-trips (browsers, Deno, Node launched with `--localstorage-file`),
+ * {@link createFileSink} under Node. The noop sink is intentionally absent:
+ * the console sink verifies wherever `console` and `queueMicrotask` exist,
+ * so the default logger has a backend in every supported runtime, and a
+ * custom `createLogger` whose sinks all fail verification surfaces the
+ * "No logging backends available" error instead of silently discarding.
+ * The OPFS sink is exported
+ * but no longer a default: its stream stages writes until a close that a
+ * crash never performs, so IndexedDB holds the persistent-browser slot; see
+ * `DECISIONS.md`.
+ */
+const defaultSinks: readonly Sink[] = [
+  createConsoleSink(),
+  createIndexedDbSink(),
+  createSessionStorageSink(),
+  createLocalStorageSink(),
+  createFileSink(),
+];
+
+/**
+ * Default multi-sink logger plus its eager readiness promise, built by
+ * applying {@link createLogger} to {@link defaultSinks}.
+ */
+const {
+  initPromise: defaultInitPromise,
+  logger: defaultLogger,
+} = createLogger({ sinks: defaultSinks, },);
+
+/**
+ * Eager readiness promise. Consumers do not need to await this before logging;
+ * {@link Logger.flush} awaits it internally, and startup records replay to
+ * async sinks as they become available.
+ */
+export const initPromise: Promise<void> = defaultInitPromise;
+
+/**
+ * Multi-sink logger that writes to all available backends.
+ * Startup records replay to async sinks that verify after the log call.
+ * Log calls throw only when initialization proves no backend is available,
+ * which the console sink prevents in every supported runtime.
+ *
+ * @example
+ * ```ts
+ * import { logger, } from '\@monochromatic-dev/module-logger/logger';
+ *
+ * logger.error('unexpected shutdown',);
+ * await logger.flush();
+ * ```
+ */
+export const logger: Logger = defaultLogger;

package/src/logger.unit.test.ts

@@ -0,0 +1,190 @@
+import {
+  describe,
+  expect,
+  it,
+} from '@monochromatic-dev/module-test/ts';
+import {
+  logger,
+} from '@monochromatic-dev/module-logger';
+
+await describe({
+  name: logger.constructor.name,
+  children: [
+    it({
+      name: 'logger has all six log level methods',
+      fn: async () => {
+        expect(typeof logger.trace,).toBe('function',);
+        expect(typeof logger.debug,).toBe('function',);
+        expect(typeof logger.info,).toBe('function',);
+        expect(typeof logger.warn,).toBe('function',);
+        expect(typeof logger.error,).toBe('function',);
+        expect(typeof logger.fatal,).toBe('function',);
+      },
+    },),
+
+    it({
+      name: 'trace method accepts string message',
+      fn: async () => {
+        expect(() => {
+          logger.trace('test trace message',);
+        },)
+          .not
+          .toThrow();
+      },
+    },),
+
+    it({
+      name: 'debug method accepts string message',
+      fn: async () => {
+        expect(() => {
+          logger.debug('test debug message',);
+        },)
+          .not
+          .toThrow();
+      },
+    },),
+
+    it({
+      name: 'info method accepts string message',
+      fn: async () => {
+        expect(() => {
+          logger.info('test info message',);
+        },)
+          .not
+          .toThrow();
+      },
+    },),
+
+    it({
+      name: 'warn method accepts string message',
+      fn: async () => {
+        expect(() => {
+          logger.warn('test warn message',);
+        },)
+          .not
+          .toThrow();
+      },
+    },),
+
+    it({
+      name: 'error method accepts string message',
+      fn: async () => {
+        expect(() => {
+          logger.error('test error message',);
+        },)
+          .not
+          .toThrow();
+      },
+    },),
+
+    it({
+      name: 'fatal method accepts string message',
+      fn: async () => {
+        expect(() => {
+          logger.fatal('test fatal message',);
+        },)
+          .not
+          .toThrow();
+      },
+    },),
+
+    it({
+      name: 'logs with empty string message',
+      fn: async () => {
+        expect(() => {
+          logger.info('',);
+        },)
+          .not
+          .toThrow();
+      },
+    },),
+
+    it({
+      name: 'logs with unicode message',
+      fn: async () => {
+        expect(() => {
+          logger.info('Hello 世界 🌍',);
+        },)
+          .not
+          .toThrow();
+      },
+    },),
+
+    it({
+      name: 'logs with multiline message',
+      fn: async () => {
+        expect(() => {
+          logger.info('line1\nline2\nline3',);
+        },)
+          .not
+          .toThrow();
+      },
+    },),
+
+    it({
+      name: 'logs with special characters',
+      fn: async () => {
+        expect(() => {
+          logger.info('Special: <script>alert("xss")</script>',);
+        },)
+          .not
+          .toThrow();
+      },
+    },),
+
+    it({
+      name: 'logs with JSON-like content',
+      fn: async () => {
+        expect(() => {
+          logger.info('{"key": "value", "count": 42}',);
+        },)
+          .not
+          .toThrow();
+      },
+    },),
+
+    it({
+      name: 'handles rapid successive logs',
+      fn: async () => {
+        expect(() => {
+          const RAPID_LOG_COUNT = 100;
+          for (let logIndex = 0; logIndex < RAPID_LOG_COUNT; logIndex++)
+            logger.debug(`rapid log ${logIndex}`,);
+        },)
+          .not
+          .toThrow();
+      },
+    },),
+
+    it({
+      name: 'flush is a callable method returning a promise',
+      fn: async () => {
+        expect(typeof logger.flush,)
+          .toBe('function',);
+        const result = logger.flush();
+        expect(result instanceof Promise,)
+          .toBe(true,);
+        await result;
+      },
+    },),
+
+    it({
+      name: 'flush drains buffered console records',
+      fn: async () => {
+        // The console sink batches on microtasks; after a sync burst
+        // of logs, flush should resolve after the console has actually
+        // received the records. We cannot easily assert the count here
+        // without re-spying (the default logger owns its sinks), so this
+        // test only verifies that flush resolves after at least one
+        // microtask tick rather than returning an already-settled promise
+        // that misses the flush.
+        logger.info('pre-flush 1',);
+        logger.info('pre-flush 2',);
+        logger.info('pre-flush 3',);
+        await expect(logger.flush(),)
+          .resolves
+          .toBeUndefined();
+      },
+    },),
+  ],
+},);

package/src/sink/console-control-chars.ts

@@ -0,0 +1,140 @@
+/**
+ * Console-bound text crosses a syntax boundary: a terminal interprets C0 and
+ * C1 control characters as commands (clear screen, set title, move cursor,
+ * write clipboard). Log messages can carry attacker-influenced text, so the
+ * console sink neutralizes every control character except newline and tab
+ * before the text reaches `console.*` or `process.stderr`.
+ *
+ * @module
+ */
+
+/**
+ * First code unit above the C0 control range; everything below it except
+ * newline and tab is neutralized.
+ */
+const C0_CONTROL_LIMIT = 0x20;
+
+/**
+ * Newline stays literal: multi-line messages (stack traces) are a core use.
+ */
+const NEWLINE_CODE_UNIT = 0x0A;
+
+/**
+ * Tab stays literal: indentation in multi-line messages is harmless.
+ */
+const TAB_CODE_UNIT = 0x09;
+
+/**
+ * DEL sits alone above the printable ASCII range and is a control character.
+ */
+const DELETE_CODE_UNIT = 0x7F;
+
+/**
+ * First code unit of the C1 control range (8-bit CSI, OSC, and friends).
+ */
+const C1_CONTROL_START = 0x80;
+
+/**
+ * Last code unit of the C1 control range.
+ */
+const C1_CONTROL_END = 0x9F;
+
+/**
+ * Radix for the hexadecimal digits inside a `\uXXXX` escape.
+ */
+const HEX_RADIX = 16;
+
+/**
+ * Digit count of a `\uXXXX` escape, zero-padded on the left.
+ */
+const UNICODE_ESCAPE_WIDTH = 4;
+
+/**
+ * Reports whether one UTF-16 code unit is a control character the console
+ * sink must neutralize.
+ *
+ * @param codeUnit - UTF-16 code unit read from the message.
+ *
+ * @returns Whether the code unit is a C0 control other than newline and tab,
+ * DEL, or a C1 control.
+ *
+ * @example
+ * ```ts
+ * isNeutralizedControl(0x1B); // true (ESC)
+ * isNeutralizedControl(0x0A); // false (newline stays)
+ * ```
+ */
+function isNeutralizedControl(codeUnit: number,): boolean {
+  if (codeUnit < C0_CONTROL_LIMIT)
+    return (codeUnit !== NEWLINE_CODE_UNIT) && (codeUnit !== TAB_CODE_UNIT);
+
+  if (codeUnit === DELETE_CODE_UNIT)
+    return true;
+
+  return (codeUnit >= C1_CONTROL_START) && (codeUnit <= C1_CONTROL_END);
+}
+
+/**
+ * Renders one code unit as a `\uXXXX` escape with uppercase hex digits (the
+ * repository's escape-case convention) so the attempted control stays
+ * visible for forensics instead of vanishing.
+ *
+ * @param codeUnit - UTF-16 code unit to escape.
+ *
+ * @returns Six-character escape such as `\u001B`.
+ *
+ * @example
+ * ```ts
+ * escapeCodeUnit(0x1B); // '\\u001B'
+ * ```
+ */
+function escapeCodeUnit(codeUnit: number,): string {
+  return `\\u${
+    codeUnit
+      .toString(HEX_RADIX,)
+      .toUpperCase()
+      .padStart(
+        UNICODE_ESCAPE_WIDTH,
+        '0',
+      )
+  }`;
+}
+
+/**
+ * Neutralizes terminal control characters in console-bound text. One linear
+ * pass over the code points: each neutralized control becomes a `\uXXXX`
+ * escape, everything else is copied through, and newline and tab pass
+ * untouched. Well-formed and malformed escape sequences get no
+ * special treatment because the introducer byte itself is neutralized, so a
+ * trailing lone ESC, an unterminated OSC, and a nested ESC all lose their
+ * teeth the same way.
+ *
+ * @param text - Message text destined for `console.*` or `process.stderr`.
+ *
+ * @returns Text with every neutralized control rendered as `\uXXXX`.
+ *
+ * @example
+ * ```ts
+ * neutralizeControlCharacters('title:\u001B]0;x\u0007 ok\n\tnext');
+ * // => 'title:\\u001B]0;x\\u0007 ok\n\tnext'
+ * ```
+ */
+export function neutralizeControlCharacters(text: string,): string {
+  /**
+   * Output pieces in input order: each code point either verbatim or as its
+   * escape, joined once at the end so no per-character string rebuild occurs.
+   */
+  const pieces: string[] = [];
+  for (const character of text) {
+    /**
+     * Leading code unit of this iteration element. String iteration walks
+     * code points, so a surrogate pair arrives as one two-unit string whose
+     * lead surrogate is never a control, and a lone surrogate passes the
+     * same way.
+     */
+    // oxlint-disable-next-line unicorn/prefer-code-point -- Classifier reads the lead code unit on purpose; controls below U+00A0 never sit inside a surrogate pair, so code-point decoding adds nothing.
+    const codeUnit = character.charCodeAt(0,);
+    pieces.push(isNeutralizedControl(codeUnit,) ? escapeCodeUnit(codeUnit,) : character,);
+  }
+  return pieces.join('',);
+}

package/src/sink/console-control-chars.unit.test.ts

@@ -0,0 +1,206 @@
+import {
+  describe,
+  expect,
+  it,
+} from '@monochromatic-dev/module-test/ts';
+import {
+  _neutralizeControlCharacters as neutralizeControlCharacters,
+} from '@monochromatic-dev/module-logger';
+
+/**
+ * Adversarial inputs at the terminal boundary paired with the exact output
+ * the neutralizer must produce. Each case names the attack or the malformed
+ * shape it pins.
+ */
+const BOUNDARY_CASES: readonly {
+  readonly name: string;
+  readonly input: string;
+  readonly expected: string;
+}[] = [
+  {
+    name: 'OSC title-set sequence',
+    input: 'title:\u001B]0;PWNED\u0007 ok',
+    expected: 'title:\\u001B]0;PWNED\\u0007 ok',
+  },
+  {
+    name: 'CSI clear-screen sequence',
+    input: 'clear:\u001B[2J',
+    expected: 'clear:\\u001B[2J',
+  },
+  {
+    name: 'SGR color sequence (no allowlist)',
+    input: '\u001B[31mred\u001B[0m',
+    expected: '\\u001B[31mred\\u001B[0m',
+  },
+  {
+    name: 'trailing lone ESC',
+    input: 'tail\u001B',
+    expected: 'tail\\u001B',
+  },
+  {
+    name: 'ESC [ with no final byte',
+    input: 'open\u001B[',
+    expected: 'open\\u001B[',
+  },
+  {
+    name: 'unterminated OSC',
+    input: '\u001B]2;never closed',
+    expected: '\\u001B]2;never closed',
+  },
+  {
+    name: 'nested ESC inside a sequence',
+    input: '\u001B[\u001B[2J',
+    expected: '\\u001B[\\u001B[2J',
+  },
+  {
+    name: '8-bit C1 CSI',
+    input: 'c1:\u009B2J',
+    expected: 'c1:\\u009B2J',
+  },
+  {
+    name: 'DEL',
+    input: 'del:\u007F',
+    expected: 'del:\\u007F',
+  },
+  {
+    name: 'NUL',
+    input: 'nul:\u0000end',
+    expected: 'nul:\\u0000end',
+  },
+  {
+    name: 'carriage return (line overwrite)',
+    input: 'real\rfake',
+    expected: 'real\\u000Dfake',
+  },
+  {
+    name: 'backspace',
+    input: 'ab\bc',
+    expected: 'ab\\u0008c',
+  },
+];
+
+/**
+ * Inputs the neutralizer must return unchanged.
+ */
+const PASSTHROUGH_CASES: readonly {
+  readonly name: string;
+  readonly input: string;
+}[] = [
+  {
+    name: 'plain ASCII',
+    input: 'server started on port 3000',
+  },
+  {
+    name: 'empty string',
+    input: '',
+  },
+  {
+    name: 'newline and tab',
+    input: 'line one\n\tindented two\n',
+  },
+  {
+    name: 'non-ASCII text and emoji',
+    input: 'héllo wörld 🚀 日本語',
+  },
+  {
+    name: 'lone surrogate',
+    input: 'x\uD83Dy',
+  },
+  {
+    name: 'format specifiers',
+    input: '%s %d %j %%',
+  },
+  {
+    name: 'code point just above the C1 range',
+    input: 'nbsp:\u00A0end',
+  },
+];
+
+/**
+ * One past the last C1 code unit; the exhaustive sweep covers every code unit
+ * below it.
+ */
+const CONTROL_SWEEP_LENGTH = 0xA0;
+
+/**
+ * Reports whether an output code unit is still a control the boundary forbids.
+ *
+ * @param codeUnit - UTF-16 code unit read from neutralizer output.
+ *
+ * @returns Whether the code unit should have been neutralized.
+ */
+function isForbiddenControl(codeUnit: number,): boolean {
+  if (codeUnit < 0x20)
+    return (codeUnit !== 0x0A) && (codeUnit !== 0x09);
+  if (codeUnit === 0x7F)
+    return true;
+  return (codeUnit >= 0x80) && (codeUnit <= 0x9F);
+}
+
+await describe({
+  name: neutralizeControlCharacters.name,
+  children: [
+    //region Neutralized controls
+
+    ...BOUNDARY_CASES.map(function mapBoundaryCase(boundaryCase,) {
+      return it({
+        name: `neutralizes ${boundaryCase.name}`,
+        fn: async () => {
+          expect(neutralizeControlCharacters(boundaryCase.input,),)
+            .toBe(boundaryCase.expected,);
+        },
+      },);
+    },),
+
+    it({
+      name: 'output never contains a neutralized control after the pass',
+      fn: async () => {
+        /**
+         * Every code unit from NUL through U+009F, in one string.
+         */
+        const allControls = Array.from(
+          { length: CONTROL_SWEEP_LENGTH, },
+          function toChar(
+            _unused,
+            index,
+          ) {
+            return String.fromCodePoint(index,);
+          },
+        )
+          .join('',);
+        /**
+         * Neutralized sweep; only newline and tab may survive as controls.
+         */
+        const output = neutralizeControlCharacters(allControls,);
+        /**
+         * Output code units that are still forbidden controls; must stay empty.
+         */
+        const leaked: number[] = [];
+        for (const character of output) {
+          // oxlint-disable-next-line unicorn/prefer-code-point -- The sweep classifies lead code units below U+00A0, which never sit inside a surrogate pair.
+          const codeUnit = character.charCodeAt(0,);
+          if (isForbiddenControl(codeUnit,))
+            leaked.push(codeUnit,);
+        }
+        expect(leaked,)
+          .toEqual([],);
+      },
+    },),
+
+    //endregion Neutralized controls
+
+    //region Passthrough
+
+    ...PASSTHROUGH_CASES.map(function mapPassthroughCase(passthroughCase,) {
+      return it({
+        name: `leaves ${passthroughCase.name} untouched`,
+        fn: async () => {
+          expect(neutralizeControlCharacters(passthroughCase.input,),)
+            .toBe(passthroughCase.input,);
+        },
+      },);
+    },),
+
+    //endregion Passthrough
+  ],
+},);