@monochromatic-dev/module-logger 0.1.0 → 0.3.0

package/src/default-sinks.neutral.ts

@@ -0,0 +1,34 @@
+import { createConsoleSink, } from './sink/console.ts';
+import { createIndexedDbSink, } from './sink/indexed-db.ts';
+import { createLocalStorageSink, } from './sink/local-storage.ts';
+import { createSessionStorageSink, } from './sink/session-storage.ts';
+
+import type { Sink, } from './types.ts';
+
+/**
+ Default sink backends the platform-neutral artifact attempts, in priority
+ order. Chosen at bundle time: `package.json` maps `#default-sinks` to this
+ module under the `default` condition, so every non-Node resolution
+ (browsers, Deno, Bun, workers) inlines this list without a runtime
+ platform probe. 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, Deno),
+ {@link createLocalStorageSink} wherever `localStorage` round-trips
+ (browsers, Deno). 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 file sink
+ is absent because its static `node:fs/promises` import cannot load outside
+ Node; it ships through the `./node` subpath and the Node default list
+ instead. The OPFS sink is exported from `./browser` but not a default:
+ its stream stages writes until a close that a crash never performs, so
+ IndexedDB holds the persistent-browser slot; see `DECISIONS.md`.
+ */
+export const defaultSinks: readonly Sink[] = [
+  createConsoleSink(),
+  createIndexedDbSink(),
+  createSessionStorageSink(),
+  createLocalStorageSink(),
+];

package/src/default-sinks.node.ts

@@ -0,0 +1,32 @@
+import { createConsoleSink, } from './sink/console.ts';
+import { createFileSink, } from './sink/file.ts';
+import { createLocalStorageSink, } from './sink/local-storage.ts';
+import { createSessionStorageSink, } from './sink/session-storage.ts';
+
+import type { Sink, } from './types.ts';
+
+/**
+ Default sink backends the Node artifact attempts, in priority order.
+ Chosen at bundle time: `package.json` maps `#default-sinks` to this module
+ under the `node` condition, so `logger.ts` inlines this list without a
+ runtime platform probe. Each runtime keeps only the sinks whose `verify`
+ confirms its backend: {@link createConsoleSink} everywhere,
+ {@link createSessionStorageSink} wherever web storage round-trips (Node
+ 22+, Deno), {@link createLocalStorageSink} wherever `localStorage`
+ round-trips (Deno, Node launched with `--localstorage-file`), and
+ {@link createFileSink} wherever an ancestor `node_modules` exists. 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 IndexedDB and OPFS sinks are absent
+ because Node exposes neither `indexedDB` nor `navigator.storage`; they
+ ship through the `./browser` subpath instead, keeping their probes and
+ code out of this artifact.
+ */
+export const defaultSinks: readonly Sink[] = [
+  createConsoleSink(),
+  createSessionStorageSink(),
+  createLocalStorageSink(),
+  createFileSink(),
+];

package/src/error-format.ts

@@ -1,32 +1,32 @@
 /**
- * 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
+ 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'),
- * });
- * ```
+ 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(
   {

package/src/index.ts

@@ -1,6 +1,8 @@
 export {
   createLogger,
   DEFAULT_FLUSH_DEADLINE_MS,
+  DEFAULT_VERIFY_TIMEOUT_MS,
+  STARTUP_BUFFER_CAP,
 } from './create-logger.ts';
 export {
   initPromise,

package/src/logger.ts

@@ -1,42 +1,15 @@
+import { defaultSinks, } 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 {
-  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(),
-];
+import type { Logger, } from './types.ts';
 
 /**
- * Default multi-sink logger plus its eager readiness promise, built by
- * applying {@link createLogger} to {@link defaultSinks}.
+ Default multi-sink logger plus its eager readiness promise, built by
+ applying {@link createLogger} to the platform-selected `defaultSinks`
+ (`default-sinks.node.ts` under the `node` condition,
+ `default-sinks.neutral.ts` otherwise; see the `imports` map in
+ `package.json`).
  */
 const {
   initPromise: defaultInitPromise,
@@ -44,24 +17,24 @@ const {
 } = 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.
+ 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();
- * ```
+ 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/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/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) {