@monochromatic-dev/module-logger 0.2.0 → 0.3.0

package/src/sink/local-storage.ts

@@ -9,23 +9,23 @@ import type {
 } from '../types.ts';
 
 /**
- * Node CLI flag that backs `localStorage` with a file; without it Node 26
- * leaves `globalThis.localStorage` undefined and prints an
- * `ExperimentalWarning` on stderr the moment the getter is touched.
+ Node CLI flag that backs `localStorage` with a file; without it Node 26
+ leaves `globalThis.localStorage` undefined and prints an
+ `ExperimentalWarning` on stderr the moment the getter is touched.
  */
 const NODE_LOCALSTORAGE_FLAG = '--localstorage-file';
 
 /**
- * Reports whether this is a flagless plain-Node process, where
- * `globalThis.localStorage` is undefined and merely touching the getter
- * prints Node's ExperimentalWarning on stderr for every consumer, so `verify`
- * skips the probe without any access. The flag is honored both on the command
- * line (`process.execArgv`) and through `NODE_OPTIONS` (verified on Node 26;
- * `execArgv` does not echo `NODE_OPTIONS` flags, so both are checked). A DOM
- * host (such as an Electron renderer, which carries `process.versions.node`
- * alongside a real `localStorage`) is exempt and probes normally.
- *
- * @returns Whether the probe must be skipped because Node would only warn.
+ Reports whether this is a flagless plain-Node process, where
+ `globalThis.localStorage` is undefined and merely touching the getter
+ prints Node's ExperimentalWarning on stderr for every consumer, so `verify`
+ skips the probe without any access. The flag is honored both on the command
+ line (`process.execArgv`) and through `NODE_OPTIONS` (verified on Node 26;
+ `execArgv` does not echo `NODE_OPTIONS` flags, so both are checked). A DOM
+ host (such as an Electron renderer, which carries `process.versions.node`
+ alongside a real `localStorage`) is exempt and probes normally.
+ 
+ @returns Whether the probe must be skipped because Node would only warn.
  */
 function nodeWithoutLocalStorageFile(): boolean {
   if (detectWebStorageRuntime() !== 'node')
@@ -33,55 +33,55 @@ function nodeWithoutLocalStorageFile(): boolean {
   if ('document' in globalThis)
     return false;
   /**
-   * Whether the backing-file flag reached this process on the command line.
+   Whether the backing-file flag reached this process on the command line.
    */
   const flaggedInExecArgv = process.execArgv
     .some(function startsWithFlag(argument: string,) {
       return argument.startsWith(NODE_LOCALSTORAGE_FLAG,);
     },);
   /**
-   * Raw `NODE_OPTIONS` value, absent when the variable is unset; `execArgv`
-   * does not echo flags arriving through it, so it is scanned separately.
+   Raw `NODE_OPTIONS` value, absent when the variable is unset; `execArgv`
+   does not echo flags arriving through it, so it is scanned separately.
    */
   const nodeOptions = process.env
     .NODE_OPTIONS;
   /**
-   * Whether the backing-file flag reached this process through `NODE_OPTIONS`.
+   Whether the backing-file flag reached this process through `NODE_OPTIONS`.
    */
   const flaggedInNodeOptions = (nodeOptions ?? '').includes(NODE_LOCALSTORAGE_FLAG,);
   return !(flaggedInExecArgv || flaggedInNodeOptions);
 }
 
 /**
- * Verifies localStorage actually persists data. Stateless: the logger calls
- * this once per sink at startup and owns the resulting availability, so no
- * verified/available flag is kept here.
- *
- * Election is by probe alone: any runtime whose `localStorage` round-trips
- * (browsers, Deno, Node launched with `--localstorage-file`) keeps the sink.
- * The one short-circuit, {@link nodeWithoutLocalStorageFile}, returns the
- * same `false` the probe would and exists only to keep Node's access warning
- * off every consumer's stderr, not to gate by runtime brand.
- *
- * @returns Whether localStorage is available and round-trips a probe write.
- *
- * @example
- * ```ts
- * if (await verifyLocalStorage()) {
- *   // localStorage usable
- * }
- * ```
+ Verifies localStorage actually persists data. Stateless: the logger calls
+ this once per sink at startup and owns the resulting availability, so no
+ verified/available flag is kept here.
+ 
+ Election is by probe alone: any runtime whose `localStorage` round-trips
+ (browsers, Deno, Node launched with `--localstorage-file`) keeps the sink.
+ The one short-circuit, {@link nodeWithoutLocalStorageFile}, returns the
+ same `false` the probe would and exists only to keep Node's access warning
+ off every consumer's stderr, not to gate by runtime brand.
+ 
+ @returns Whether localStorage is available and round-trips a probe write.
+ 
+ @example
+ ```ts
+ if (await verifyLocalStorage()) {
+   // localStorage usable
+ }
+ ```
  */
 function verifyLocalStorage(): Promise<boolean> {
   if (nodeWithoutLocalStorageFile())
     return Promise.resolve(false,);
   try {
     /**
-     * Sentinel key used only for the probe write/read; removed afterward to avoid polluting real log entries.
+     Sentinel key used only for the probe write/read; removed afterward to avoid polluting real log entries.
      */
     const testKey = '__monochromatic_verify__';
     /**
-     * Timestamp-based probe value so concurrent verifications never read each other's writes.
+     Timestamp-based probe value so concurrent verifications never read each other's writes.
      */
     const testValue = `test-${Date.now()}`;
     globalThis.localStorage
@@ -90,7 +90,7 @@ function verifyLocalStorage(): Promise<boolean> {
       testValue,
     );
     /**
-     * Probe value read back from storage; equality with `testValue` proves writes actually persist.
+     Probe value read back from storage; equality with `testValue` proves writes actually persist.
      */
     const readBack = globalThis.localStorage
       .getItem(testKey,);
@@ -109,49 +109,49 @@ function verifyLocalStorage(): Promise<boolean> {
 }
 
 /**
- * Builds a localStorage sink that buffers serialized records through the
- * shared {@link createRecordBuffer} policy and persists each newline-joined
- * JSONL batch under a run-scoped counter-incremented key through
- * {@link createLocalStorageStore}. One uniform write path runs on every
- * runtime; no per-runtime mode exists. Flush triggers (32 KiB in-write cap,
- * `warn`-or-worse severity, 250 ms quiet-period deadline, page lifecycle,
- * and the `flush` hook) are the buffer's; see {@link createRecordBuffer}.
- *
- * Unlike the sessionStorage sink, whose store dies with the tab, this sink's
- * batches survive tab close and browser restart, bounded by oldest-first
- * eviction at half the localStorage quota; that makes it the web storage sink
- * whose records remain inspectable after a full crash-and-restart.
- *
- * @returns Sink backed by web `localStorage`.
- *
- * @example
- * ```ts
- * const { logger } = createLogger({ sinks: [createLocalStorageSink()] });
- * logger.info('user signed in'); // buffered
- * logger.warn('quota near');     // flushes both records in one batch
- * ```
+ Builds a localStorage sink that buffers serialized records through the
+ shared {@link createRecordBuffer} policy and persists each newline-joined
+ JSONL batch under a run-scoped counter-incremented key through
+ {@link createLocalStorageStore}. One uniform write path runs on every
+ runtime; no per-runtime mode exists. Flush triggers (32 KiB in-write cap,
+ `warn`-or-worse severity, 250 ms quiet-period deadline, page lifecycle,
+ and the `flush` hook) are the buffer's; see {@link createRecordBuffer}.
+ 
+ Unlike the sessionStorage sink, whose store dies with the tab, this sink's
+ batches survive tab close and browser restart, bounded by oldest-first
+ eviction at half the localStorage quota; that makes it the web storage sink
+ whose records remain inspectable after a full crash-and-restart.
+ 
+ @returns Sink backed by web `localStorage`.
+ 
+ @example
+ ```ts
+ const { logger } = createLogger({ sinks: [createLocalStorageSink()] });
+ logger.info('user signed in'); // buffered
+ logger.warn('quota near');     // flushes both records in one batch
+ ```
  */
 export function createLocalStorageSink(): Sink {
   /**
-   * Persistence engine owning run identity, key allocation, prior-run
-   * adoption, footprint accounting, and quota eviction; the buffer decides
-   * when a batch is handed to it.
+   Persistence engine owning run identity, key allocation, prior-run
+   adoption, footprint accounting, and quota eviction; the buffer decides
+   when a batch is handed to it.
    */
   const store = createLocalStorageStore();
 
   /**
-   * Shared buffering stage; every flush trigger lands one joined batch in the
-   * persistence engine synchronously.
+   Shared buffering stage; every flush trigger lands one joined batch in the
+   persistence engine synchronously.
    */
   const buffer = createRecordBuffer({ onFlush: store.persist, },);
 
   /**
-   * Buffers a log record through the shared policy; see
-   * {@link createRecordBuffer} for the flush triggers.
-   *
-   * @param record - Log record to buffer and eventually persist.
-   *
-   * @mutates record - `JSON.stringify` may invoke `toJSON`, getters, or proxy traps.
+   Buffers a log record through the shared policy; see
+   {@link createRecordBuffer} for the flush triggers.
+   
+   @param record - Log record to buffer and eventually persist.
+   
+   @mutates record - `JSON.stringify` may invoke `toJSON`, getters, or proxy traps.
    */
   function write(record: {
     level: Level;
@@ -166,8 +166,8 @@ export function createLocalStorageSink(): Sink {
   }
 
   /**
-   * Drains the buffer into the persistence engine; the drain is synchronous,
-   * so the batch has landed by the time the resolved promise is observed.
+   Drains the buffer into the persistence engine; the drain is synchronous,
+   so the batch has landed by the time the resolved promise is observed.
    */
   function flush(): Promise<void> {
     buffer.drain();

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

@@ -9,20 +9,20 @@ import {
 } from '@monochromatic-dev/module-logger';
 
 /**
- * Sink factories under test, read from the built artifact's `sinks` namespace.
+ Sink factories under test, read from the built artifact's `sinks` namespace.
  */
 const {
   createLocalStorageSink,
 } = sinks;
 
 /**
- * Installs `fake` as `globalThis.localStorage` via the property descriptor,
- * 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.
+ Installs `fake` as `globalThis.localStorage` via the property descriptor,
+ 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',);
@@ -41,12 +41,12 @@ function installFakeLocalStorage(fake: Storage,): Disposable {
 }
 
 /**
- * Installs a minimal fake `globalThis.document` (absent under Node) so the
- * sink under test takes the DOM-host verify path instead of the flagless-Node
- * short-circuit, restoring or removing the global when the returned guard
- * leaves `using` scope.
- *
- * @returns Disposable that restores the original `document` on exit.
+ Installs a minimal fake `globalThis.document` (absent under Node) so the
+ sink under test takes the DOM-host verify path instead of the flagless-Node
+ short-circuit, restoring or removing the global when the returned guard
+ leaves `using` scope.
+ 
+ @returns Disposable that restores the original `document` on exit.
  */
 function installFakeDocument(): Disposable {
   const had = 'document' in globalThis;
@@ -66,11 +66,11 @@ function installFakeDocument(): Disposable {
 }
 
 /**
- * Builds an in-memory `Storage` stand-in with enumeration support, exposing
- * the raw `backing` map so a test can assert exactly which keys and values
- * landed.
- *
- * @returns Storage stand-in exposing the raw `backing` map.
+ Builds an in-memory `Storage` stand-in with enumeration support, exposing
+ the raw `backing` map so a test can assert exactly which keys and values
+ landed.
+ 
+ @returns Storage stand-in exposing the raw `backing` map.
  */
 function createFakeStorage(): Storage & { readonly backing: Map<string, string>; } {
   const backing = new Map<string, string>();
@@ -98,11 +98,11 @@ function createFakeStorage(): Storage & { readonly backing: Map<string, string>;
 }
 
 /**
- * Captures `console.warn` output, restoring the real method when the returned
- * guard leaves `using` scope, so a test can prove the flagless-Node
- * short-circuit stays silent.
- *
- * @returns Disposable exposing captured warn lines as `calls`.
+ Captures `console.warn` output, restoring the real method when the returned
+ guard leaves `using` scope, so a test can prove the flagless-Node
+ short-circuit stays silent.
+ 
+ @returns Disposable exposing captured warn lines as `calls`.
  */
 function spyConsoleWarn(): Disposable & { readonly calls: string[]; } {
   const original = console.warn;
@@ -163,7 +163,7 @@ await describe({
         const sink = createLocalStorageSink();
 
         /**
-         * Routine record that must stay buffered on its own.
+         Routine record that must stay buffered on its own.
          */
         const first = {
           level: 'info' as const,
@@ -171,7 +171,7 @@ await describe({
           timestamp: 1,
         };
         /**
-         * Urgent record whose severity flushes itself and `first` together.
+         Urgent record whose severity flushes itself and `first` together.
          */
         const second = {
           level: 'warn' as const,
@@ -187,7 +187,7 @@ await describe({
         expect([...fake.backing.values(),],)
           .toEqual([`${JSON.stringify(first,)}\n${JSON.stringify(second,)}`,],);
         /**
-         * Identity of the landed key; the first batch of a run takes index zero.
+         Identity of the landed key; the first batch of a run takes index zero.
          */
         const { parsed: landed, } = parseLogKey([...fake.backing.keys(),][0] ?? '',);
         expect(landed?.index,)

package/src/sink/noop.ts

@@ -4,19 +4,19 @@ import type {
 } from '../types.ts';
 
 /**
- * Noop verification: the sink is always available, so it never throws nor
- * needs setup.
- *
- * @returns Always-resolved `true`.
+ Noop verification: the sink is always available, so it never throws nor
+ needs setup.
+ 
+ @returns Always-resolved `true`.
  */
 function verify(): Promise<boolean> {
   return Promise.resolve(true,);
 }
 
 /**
- * Discards a log record. Matches the `Sink['write']` signature.
- *
- * @param _record - Log record to discard.
+ Discards a log record. Matches the `Sink['write']` signature.
+ 
+ @param _record - Log record to discard.
  */
 function write(_record: LogRecord,): Promise<void> {
   // Intentionally discards all logs; resolves immediately to match the async Sink contract.
@@ -24,19 +24,19 @@ function write(_record: LogRecord,): Promise<void> {
 }
 
 /**
- * Builds a noop sink that discards every record and always verifies as
- * available. Stateless, so the returned adapters share the same functions;
- * the factory shape merely matches the other sinks. Useful as a stand-in
- * that disables logging without removing log calls.
- *
- * @returns Sink that discards all records and exposes no `flush` (nothing
- * is buffered).
- *
- * @example
- * ```ts
- * const { logger } = createLogger({ sinks: [createNoopSink()] });
- * logger.info('goes nowhere');
- * ```
+ Builds a noop sink that discards every record and always verifies as
+ available. Stateless, so the returned adapters share the same functions;
+ the factory shape merely matches the other sinks. Useful as a stand-in
+ that disables logging without removing log calls.
+ 
+ @returns Sink that discards all records and exposes no `flush` (nothing
+ is buffered).
+ 
+ @example
+ ```ts
+ const { logger } = createLogger({ sinks: [createNoopSink()] });
+ logger.info('goes nowhere');
+ ```
  */
 export function createNoopSink(): Sink {
   return {

package/src/sink/noop.unit.test.ts

@@ -8,7 +8,7 @@ import {
 } from '@monochromatic-dev/module-logger';
 
 /**
- * Sink factories under test, read from the built artifact's `sinks` namespace.
+ Sink factories under test, read from the built artifact's `sinks` namespace.
  */
 const {
   createNoopSink,

package/src/sink/opfs.browser.test.ts

@@ -7,18 +7,18 @@ import {
 
 declare global {
   // oxlint-disable-next-line typescript/consistent-type-imports -- typeof import() cannot use import type syntax
-  var moduleLogger: typeof import('@monochromatic-dev/module-logger');
+  var moduleLoggerBrowser: typeof import('@monochromatic-dev/module-logger/browser');
 }
 
 test.describe('OPFS sink', () => {
   test.beforeEach(async ({ page, },) => {
     await page.goto('/',);
-    await page.waitForFunction(() => globalThis.moduleLogger !== undefined);
+    await page.waitForFunction(() => globalThis.moduleLoggerBrowser !== undefined);
   },);
 
   test('createOpfsSink exposes a callable verify', async ({ page, },) => {
     const typeofVerify = await page.evaluate(() => {
-      const { createOpfsSink, } = globalThis.moduleLogger.sinks;
+      const { createOpfsSink, } = globalThis.moduleLoggerBrowser;
       return typeof createOpfsSink().verify;
     },);
     expect(typeofVerify,).toBe('function',);
@@ -26,7 +26,7 @@ test.describe('OPFS sink', () => {
 
   test('verify resolves a boolean', async ({ page, },) => {
     const resultType = await page.evaluate(async () => {
-      const { createOpfsSink, } = globalThis.moduleLogger.sinks;
+      const { createOpfsSink, } = globalThis.moduleLoggerBrowser;
       const resolved = await createOpfsSink().verify();
       return typeof resolved;
     },);
@@ -35,7 +35,7 @@ test.describe('OPFS sink', () => {
 
   test('verify detects OPFS availability', async ({ page, },) => {
     const result = await page.evaluate(async () => {
-      const { createOpfsSink, } = globalThis.moduleLogger.sinks;
+      const { createOpfsSink, } = globalThis.moduleLoggerBrowser;
       return createOpfsSink().verify();
     },);
     expect(result,).toBe(true,);
@@ -43,7 +43,7 @@ test.describe('OPFS sink', () => {
 
   test('sink write method exists', async ({ page, },) => {
     const typeofSink = await page.evaluate(() => {
-      const { createOpfsSink, } = globalThis.moduleLogger.sinks;
+      const { createOpfsSink, } = globalThis.moduleLoggerBrowser;
       return typeof createOpfsSink().write;
     },);
     expect(typeofSink,).toBe('function',);
@@ -51,7 +51,7 @@ test.describe('OPFS sink', () => {
 
   test('a verified sink writes records across levels and message shapes', async ({ page, },) => {
     const allSucceeded = await page.evaluate(async () => {
-      const { createOpfsSink, } = globalThis.moduleLogger.sinks;
+      const { createOpfsSink, } = globalThis.moduleLoggerBrowser;
       const sink = createOpfsSink();
       await sink.verify();
       const levels = ['trace', 'debug', 'info', 'warn', 'error', 'fatal',] as const;