@monochromatic-dev/module-logger 0.2.0 → 0.4.0

package/src/logger.ts

@@ -1,67 +1,92 @@
+import { createDefaultSinks, } from '#default-sinks';
+
 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 {
+  Level,
   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`.
+ Default logger instance and its readiness promise, built on first use.
+ */
+type DefaultInstance = {
+  readonly initPromise: Promise<void>;
+  readonly logger: Logger;
+};
+
+/**
+ Memo for the default instance. Empty until the first log or flush call, so
+ importing this module (or `tagged`, which reaches it) runs no sink
+ discovery: no timers, no I/O, no storage probes. Runtimes that forbid those
+ in global scope (Cloudflare Workers, issue #493) therefore pay nothing at
+ import and verify their sinks inside whatever handler logs first.
+ */
+const memo: { current?: DefaultInstance; } = {};
+
+/**
+ Builds the default instance on first use and returns it afterwards.
+
+ @returns Default logger and its readiness promise.
+
+ @example
+ ```ts
+ const { logger } = defaultInstance();
+ ```
  */
-const defaultSinks: readonly Sink[] = [
-  createConsoleSink(),
-  createIndexedDbSink(),
-  createSessionStorageSink(),
-  createLocalStorageSink(),
-  createFileSink(),
-];
+function defaultInstance(): DefaultInstance {
+  memo.current ??= createLogger({ sinks: createDefaultSinks(), },);
+  return memo.current;
+}
 
 /**
- * Default multi-sink logger plus its eager readiness promise, built by
- * applying {@link createLogger} to {@link defaultSinks}.
+ Builds one level method that forwards to the default instance, creating it
+ on the first call.
+
+ @param level - Severity the method logs at.
+
+ @returns Forwarding level method.
  */
-const {
-  initPromise: defaultInitPromise,
-  logger: defaultLogger,
-} = createLogger({ sinks: defaultSinks, },);
+function forward(level: Level,): (message: string,) => void {
+  return function logAtLevel(message: string,): void {
+    defaultInstance()
+      .logger[level](message,);
+  };
+}
 
 /**
- * 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.
+ Awaits the default instance's own `flush`, creating the instance first so a
+ flush before any log still verifies the sinks and drains them.
  */
-export const initPromise: Promise<void> = defaultInitPromise;
+async function flush(): Promise<void> {
+  await defaultInstance()
+    .logger
+    .flush();
+}
 
 /**
- * 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();
- * ```
+ Multi-sink logger that writes to all available backends, built lazily on
+ the first call. 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.
+ `flush()` awaits verification internally, so no readiness promise is
+ exported: awaiting one at module top level was the mistake this design
+ removes.
+
+ @example
+ ```ts
+ import { logger, } from '\@monochromatic-dev/module-logger';
+
+ logger.error('unexpected shutdown',);
+ await logger.flush();
+ ```
  */
-export const logger: Logger = defaultLogger;
+export const logger: Logger = {
+  debug: forward('debug',),
+  error: forward('error',),
+  fatal: forward('fatal',),
+  flush,
+  info: forward('info',),
+  trace: forward('trace',),
+  warn: forward('warn',),
+};

package/src/node.ts

@@ -0,0 +1,23 @@
+/**
+ Node-only entry (`\@monochromatic-dev/module-logger/node`).
+
+ Ships the file sink, whose static `node:fs/promises` and `node:path`
+ imports must never reach the platform-neutral root entry. Built only by
+ `rolldown.node.config.ts`, so the neutral artifact carries no `node:`
+ specifier at all.
+
+ @module
+ */
+
+export { createFileSink, } from './sink/file.ts';
+
+//region Internal seams
+// Underscore-prefixed re-exports let `file.unit.test.ts` exercise the ancestor
+// search through the built artifact (the `require-eventual-artifact` rule)
+// without widening the documented API; they are not part of the public
+// contract.
+export {
+  findNodeModulesUp as _findNodeModulesUp,
+  NO_NODE_MODULES_FOUND as _NO_NODE_MODULES_FOUND,
+} from './sink/file.ts';
+//endregion Internal seams

package/src/restricted-global-scope.unit.test.ts

@@ -0,0 +1,101 @@
+/**
+ Guards issue #493: evaluating the root entry in a runtime that forbids
+ timers in global scope (Cloudflare Workers throw from `setTimeout` there)
+ must produce no `logger internal error` output, because the default logger
+ is built on first use, not at import. Once a handler runs, the first log
+ call builds it and the console sink verifies normally.
+
+ The built artifact is imported dynamically inside the test so the throwing
+ `setTimeout` is in place during module evaluation; this file therefore
+ imports nothing from the logger statically.
+
+ @module
+ */
+
+import {
+  describe,
+  expect,
+  it,
+} from '@monochromatic-dev/module-test/ts';
+
+/**
+ Message the first log call inside the "handler" sends, distinct enough to
+ find in the console stub's calls.
+ */
+const HANDLER_MESSAGE = 'first log inside a handler after a restricted import';
+
+await describe({
+  name: 'default logger under a global-scope-restricted runtime',
+  // Both tests stub console methods, so they run one at a time.
+  concurrency: 1,
+  children: [
+    it({
+      name: 'importing the root entry while setTimeout throws writes no breadcrumb, and the first log inside a handler works',
+      fn: async ({ sinon, },) => {
+        const warn = sinon.stub(
+          console,
+          'warn',
+        );
+        const info = sinon.stub(
+          console,
+          'info',
+        );
+        /**
+         Timer stub that behaves like a Workers global scope: any timer is a
+         disallowed operation.
+         */
+        const forbidTimers = sinon.stub(
+          globalThis,
+          'setTimeout',
+        )
+          .throws(new Error('Disallowed operation called within global scope',),);
+        /**
+         Root entry evaluated with timers forbidden, as a Worker isolate does.
+         */
+        const entry = await import('@monochromatic-dev/module-logger');
+        /**
+         `tagged` reaches the singleton through its default parameter; wrapping
+         must not build it either.
+         */
+        const l = entry.tagged({ tag: 'restricted', },);
+        expect(warn.callCount,)
+          .toBe(0,);
+        forbidTimers.restore();
+
+        // Inside a handler, timers are allowed again: the first log builds the
+        // default logger, its sinks verify, and the console sink writes.
+        l.info(HANDLER_MESSAGE,);
+        await entry.logger.flush();
+        expect(warn.callCount,)
+          .toBe(0,);
+        /**
+         Console lines that carried the handler message.
+         */
+        const landed = info.getCalls()
+          .filter(function carriesMessage(call,) {
+            return call.args
+              .some(function mentions(argument,) {
+                return String(argument,)
+                  .includes(HANDLER_MESSAGE,);
+              },);
+          },);
+        expect(landed.length,)
+          .toBe(1,);
+      },
+    },),
+
+    it({
+      name: 'flush before any log still builds the default logger and resolves',
+      fn: async ({ sinon, },) => {
+        const warn = sinon.stub(
+          console,
+          'warn',
+        );
+        const entry = await import('@monochromatic-dev/module-logger');
+        await entry.logger.flush();
+        expect(warn.callCount,)
+          .toBe(0,);
+      },
+    },),
+  ],
+},);

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

@@ -1,68 +1,68 @@
 /**
- * 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
+ 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.
+ 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.
+ 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.
+ 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.
+ 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).
+ 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.
+ Last code unit of the C1 control range.
  */
 const C1_CONTROL_END = 0x9F;
 
 /**
- * Radix for the hexadecimal digits inside a `\uXXXX` escape.
+ Radix for the hexadecimal digits inside a `\uXXXX` escape.
  */
 const HEX_RADIX = 16;
 
 /**
- * Digit count of a `\uXXXX` escape, zero-padded on the left.
+ 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)
- * ```
+ 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)
@@ -75,18 +75,18 @@ function isNeutralizedControl(codeUnit: number,): boolean {
 }
 
 /**
- * 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'
- * ```
+ 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${
@@ -101,36 +101,36 @@ function escapeCodeUnit(codeUnit: number,): string {
 }
 
 /**
- * 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'
- * ```
+ 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.
+   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.
+     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,);

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

@@ -8,9 +8,9 @@ import {
 } 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.
+ 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;
@@ -80,7 +80,7 @@ const BOUNDARY_CASES: readonly {
 ];
 
 /**
- * Inputs the neutralizer must return unchanged.
+ Inputs the neutralizer must return unchanged.
  */
 const PASSTHROUGH_CASES: readonly {
   readonly name: string;
@@ -117,17 +117,17 @@ const PASSTHROUGH_CASES: readonly {
 ];
 
 /**
- * One past the last C1 code unit; the exhaustive sweep covers every code unit
- * below it.
+ 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.
+ 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)
@@ -156,7 +156,7 @@ await describe({
       name: 'output never contains a neutralized control after the pass',
       fn: async () => {
         /**
-         * Every code unit from NUL through U+009F, in one string.
+         Every code unit from NUL through U+009F, in one string.
          */
         const allControls = Array.from(
           { length: CONTROL_SWEEP_LENGTH, },
@@ -169,11 +169,11 @@ await describe({
         )
           .join('',);
         /**
-         * Neutralized sweep; only newline and tab may survive as controls.
+         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.
+         Output code units that are still forbidden controls; must stay empty.
          */
         const leaked: number[] = [];
         for (const character of output) {