@monochromatic-dev/module-logger 0.2.0 → 0.4.0

package/src/sink/file.ts

@@ -1,88 +1,97 @@
-import type { stat as Stat, } from 'node:fs/promises';
-import type {
-  dirname as Dirname,
-  join as Join,
+import {
+  appendFile,
+  mkdir,
+  readFile,
+  stat,
+} from 'node:fs/promises';
+import {
+  dirname,
+  join,
 } from 'node:path';
 
 import { reportLoggerInternalError, } from '../error-format.ts';
 
 import type { Sink, } from '../types.ts';
 
+//region Ancestor search
+// Locates the project the process belongs to so log files land beside its
+// `node_modules` rather than at whatever stray cwd launched the script.
+
 /**
- * Sentinel returned by {@link findNodeModulesUp} when no ancestor directory
- * contains a `node_modules`. A unique symbol so it never collides with a real
- * path string the walk might otherwise return, keeping the result free of a
- * banned `string | undefined` union.
- *
- * @example
- * ```ts
- * const dir = await findNodeModulesUp({ cwd, stat, dirname, join });
- * if (dir === NO_NODE_MODULES_FOUND) {
- *   // no ancestor project root
- * }
- * ```
+ Sentinel returned by {@link findNodeModulesUp} when no ancestor directory
+ contains a `node_modules`. A unique symbol so it never collides with a real
+ path string the walk might otherwise return, keeping the result free of a
+ banned `string | undefined` union.
+ 
+ @example
+ ```ts
+ const dir = await findNodeModulesUp({ cwd, stat, dirname, join });
+ if (dir === NO_NODE_MODULES_FOUND) {
+   // no ancestor project root
+ }
+ ```
  */
 export const NO_NODE_MODULES_FOUND: unique symbol = Symbol('logger:no-node-modules-found',);
 
 /**
- * Walks up from `cwd` to find the nearest ancestor directory containing a
- * `node_modules` subdirectory, returning that subdirectory's absolute path.
- *
- * Using find-up rather than cwd-relative placement keeps log directories
- * anchored to the project the caller actually belongs to. Without this,
- * scripts invoked from build output (e.g. `dist/`) or other stray cwds
- * would create `node_modules/.monochromatic/` inside those trees, polluting
- * shipped artifacts.
- *
- * Exported primarily so `index.unit.test.ts` can exercise both the hit
- * and miss paths directly with an injected `stat`.
- *
- * @param cwd - starting directory for the upward search
- *
- * @param stat - `node:fs/promises` stat (injected so the dynamic
- * import stays in one place)
- *
- * @param dirname - `node:path` dirname
- *
- * @param join - `node:path` join
- *
- * @param reportError - logger fault reporter injected for deterministic tests
- *
- * @returns absolute path to the nearest ancestor `node_modules`, or
- * {@link NO_NODE_MODULES_FOUND} when no ancestor contains one
- *
- * @example
- * ```ts
- * const dir = await findNodeModulesUp({ cwd: process.cwd(), stat, dirname, join });
- * ```
+ Walks up from `cwd` to find the nearest ancestor directory containing a
+ `node_modules` subdirectory, returning that subdirectory's absolute path.
+ 
+ Using find-up rather than cwd-relative placement keeps log directories
+ anchored to the project the caller actually belongs to. Without this,
+ scripts invoked from build output (e.g. `dist/`) or other stray cwds
+ would create `node_modules/.monochromatic/` inside those trees, polluting
+ shipped artifacts.
+ 
+ Exported through the `./node` subpath primarily so `file.unit.test.ts`
+ can exercise both the hit and miss paths directly with an injected `stat`.
+ 
+ @param cwd - starting directory for the upward search
+ 
+ @param stat - `node:fs/promises` stat, injected so tests drive hit,
+ miss, and fault paths deterministically without touching a real tree
+ 
+ @param dirname - `node:path` dirname
+ 
+ @param join - `node:path` join
+ 
+ @param reportError - logger fault reporter injected for deterministic tests
+ 
+ @returns absolute path to the nearest ancestor `node_modules`, or
+ {@link NO_NODE_MODULES_FOUND} when no ancestor contains one
+ 
+ @example
+ ```ts
+ const dir = await findNodeModulesUp({ cwd: process.cwd(), stat, dirname, join });
+ ```
  */
 export async function findNodeModulesUp(
   {
     cwd,
-    stat,
-    dirname,
-    join,
+    stat: statPath,
+    dirname: parentOf,
+    join: joinPath,
     reportError = reportLoggerInternalError,
   }: {
     readonly cwd: string;
-    readonly stat: typeof Stat;
-    readonly dirname: typeof Dirname;
-    readonly join: typeof Join;
+    readonly stat: typeof stat;
+    readonly dirname: typeof dirname;
+    readonly join: typeof join;
     readonly reportError?: typeof reportLoggerInternalError;
   },
 ): Promise<string | typeof NO_NODE_MODULES_FOUND> {
   /**
-   * Directory being tested in this iteration; either resolves to a node_modules or triggers the walk to the parent.
+   Directory being tested in this iteration; either resolves to a node_modules or triggers the walk to the parent.
    */
-  const candidate = join(
+  const candidate = joinPath(
     cwd,
     'node_modules',
   );
   try {
     /**
-     * Stat result for `candidate`; only directories count as a hit, guarding against a sibling file also named `node_modules`.
+     Stat result for `candidate`; only directories count as a hit, guarding against a sibling file also named `node_modules`.
      */
-    const entry = await stat(candidate,);
+    const entry = await statPath(candidate,);
     if (entry.isDirectory())
       return candidate;
   }
@@ -98,94 +107,73 @@ export async function findNodeModulesUp(
     }
   }
   /**
-   * Parent directory used by the next recursive step; equal to `cwd` only at the filesystem root, which terminates the walk.
+   Parent directory used by the next recursive step; equal to `cwd` only at the filesystem root, which terminates the walk.
    */
-  const parent = dirname(cwd,);
+  const parent = parentOf(cwd,);
   if (parent === cwd)
     return NO_NODE_MODULES_FOUND;
   return await findNodeModulesUp({
     cwd: parent,
-    stat,
-    dirname,
-    join,
+    stat: statPath,
+    dirname: parentOf,
+    join: joinPath,
     reportError,
   },);
 }
+//endregion Ancestor search
+
+//region File sink
+// Append-only JSONL sink. Imports `node:fs/promises` statically: this module
+// is reachable only from the Node artifact (the `./node` subpath and the
+// `#default-sinks` `node` condition), so the `node` export condition already
+// asserts a Node runtime and no `process.versions.node` probe is needed.
 
 /**
- * Builds a file sink that appends JSONL records to the nearest ancestor
- * `node_modules/.monochromatic/{timestamp}.log.jsonl` (resolved once during
- * verification). The resolved path, the cached `appendFile`, and the
- * verification memo live in this instance's closure (no module-global state),
- * so independent loggers and tests never share a log file or need a reset
- * hook. No `flush` hook: each `write` awaits `appendFile` directly, so there
- * is no buffered state to drain.
- *
- * @returns Sink backed by `node:fs/promises`.
- *
- * @example
- * ```ts
- * const { logger } = createLogger({ sinks: [createFileSink()] });
- * logger.error('unhandled rejection');
- * await logger.flush();
- * ```
+ Builds a file sink that appends JSONL records to the nearest ancestor
+ `node_modules/.monochromatic/{timestamp}.log.jsonl` (resolved once during
+ verification). The resolved path and the verification memo live in this
+ instance's closure (no module-global state), so independent loggers and
+ tests never share a log file or need a reset hook. No `flush` hook: each
+ `write` awaits `appendFile` directly, so there is no buffered state to
+ drain.
+ 
+ @returns Sink backed by `node:fs/promises`.
+ 
+ @example
+ ```ts
+ const { logger } = createLogger({ sinks: [createFileSink()] });
+ logger.error('unhandled rejection');
+ await logger.flush();
+ ```
  */
 export function createFileSink(): Sink {
   /**
-   * Instance-local file-sink resources. `appendFile` and `filePath` are
-   * populated during verification and read by `write`; `verifyPromise`
-   * memoizes concurrent verification so a caller arriving mid-flight shares
-   * the same async work rather than starting a second probe.
+   Instance-local file-sink resources. `filePath` is populated during
+   verification and read by `write`; `verifyPromise` memoizes concurrent
+   verification so a caller arriving mid-flight shares the same async work
+   rather than starting a second probe.
    */
   const state: {
-    // oxlint-disable-next-line typescript/consistent-type-imports -- typeof import() cannot use import type syntax
-    appendFile?: typeof import('node:fs/promises').appendFile;
     filePath?: string;
     verifyPromise?: Promise<boolean>;
   } = {};
 
   /**
-   * Actual verification work, invoked exactly once via the memoized
-   * `verifyPromise`. Resolves the log path and caches `appendFile`, marking
-   * the sink unavailable when the upward search yields
-   * {@link NO_NODE_MODULES_FOUND}. The logger owns the resulting
-   * availability, so no flag is kept here.
-   *
-   * @returns Whether file system logging is available.
+   Actual verification work, invoked exactly once via the memoized
+   `verifyPromise`. Resolves the log path, marking the sink unavailable
+   when the upward search yields {@link NO_NODE_MODULES_FOUND}. The logger
+   owns the resulting availability, so no flag is kept here.
+   
+   @returns Whether file system logging is available.
    */
   async function runVerify(): Promise<boolean> {
-    // Guard: skip dynamic import entirely outside Node.js to avoid
-    // browser console errors from attempting to fetch node: URLs.
-    if ((globalThis.process
-      === undefined)
-      || (globalThis.process
-        .versions
-        ?.node
-        === undefined))
-      return false;
-
     try {
-      // Dynamic import for Node.js modules: cache appendFile for use in write.
-      /**
-       * Dynamically imported `node:fs/promises`; held in this scope so its members are reused without re-importing.
-       */
-      const fs = await import('node:fs/promises');
-      /**
-       * Path utilities dynamically imported alongside `fs`; needed by the upward search for the closest node_modules.
-       */
-      const {
-        dirname,
-        join,
-      } = await import('node:path');
-
-      state.appendFile = fs.appendFile;
-
       /**
-       * Resolved absolute path of the closest ancestor `node_modules`, or the sentinel when none exists (e.g. a stray cwd).
+       Resolved absolute path of the closest ancestor `node_modules`, or the sentinel when none exists (e.g. a stray cwd).
        */
       const nodeModulesDir = await findNodeModulesUp({
         cwd: process.cwd(),
-        stat: fs.stat,
+        stat,
         dirname,
         join,
       },);
@@ -198,44 +186,48 @@ export function createFileSink(): Sink {
         return false;
 
       /**
-       * Directory under the chosen `node_modules` where every monochromatic log file lands.
+       Directory under the chosen `node_modules` where every monochromatic log file lands.
        */
       const LOG_DIR = join(
         nodeModulesDir,
         '.monochromatic',
       );
-      await fs.mkdir(
+      await mkdir(
         LOG_DIR,
         { recursive: true, },
       );
 
       /**
-       * ISO timestamp with colons replaced by dashes so it can be embedded in a cross-platform file name.
+       ISO timestamp with colons replaced by dashes so it can be embedded in a cross-platform file name.
        */
       const timestamp = new Date().toISOString()
         .replaceAll(
         ':',
         '-',
       );
-      state.filePath = join(
+      /**
+       Log file chosen for this sink instance; kept in a local so the probe below reads a narrowed `string`.
+       */
+      const filePath = join(
         LOG_DIR,
         `${timestamp}.log.jsonl`,
       );
+      state.filePath = filePath;
 
       // Verify by writing and reading test data.
       /**
-       * Probe record written and read back to confirm the chosen file path round-trips.
+       Probe record written and read back to confirm the chosen file path round-trips.
        */
       const testData = `{"test":true,"timestamp":${Date.now()}}\n`;
-      await state.appendFile(
-        state.filePath,
+      await appendFile(
+        filePath,
         testData,
       );
       /**
-       * Probe contents read back; matching the literal `"test":true` proves the append + read path works end-to-end.
+       Probe contents read back; matching the literal `"test":true` proves the append + read path works end-to-end.
        */
-      const content = await fs.readFile(
-        state.filePath,
+      const content = await readFile(
+        filePath,
         'utf8',
       );
       return content.includes('"test":true',);
@@ -250,10 +242,10 @@ export function createFileSink(): Sink {
   }
 
   /**
-   * Verifies file system availability via {@link runVerify}, memoizing
-   * concurrent calls so a second caller never starts a duplicate probe.
-   *
-   * @returns Whether file system logging is available.
+   Verifies file system availability via {@link runVerify}, memoizing
+   concurrent calls so a second caller never starts a duplicate probe.
+   
+   @returns Whether file system logging is available.
    */
   function verify(): Promise<boolean> {
     if (state.verifyPromise
@@ -265,20 +257,23 @@ export function createFileSink(): Sink {
   }
 
   /**
-   * Writes a single record as a JSONL line to the resolved log file.
-   *
-   * @param record - Log record to write.
-   *
-   * @mutates record - `JSON.stringify` may invoke `toJSON`, getters, or proxy traps.
+   Writes a single record as a JSONL line to the resolved log file.
+   
+   @param record - Log record to write.
+   
+   @mutates record - `JSON.stringify` may invoke `toJSON`, getters, or proxy traps.
    */
   async function write(record: object,): Promise<void> {
-    // oxlint-disable-next-line typescript/strict-boolean-expressions -- filePath/appendFile are optional (unset before verification); checking presence
-    if ((!state.filePath) || (!state.appendFile))
+    /**
+     Log file resolved by verification; unset before (or after a failed) verify, in which case the record is dropped silently.
+     */
+    const { filePath, } = state;
+    if (filePath === undefined)
       return;
 
     try {
-      await state.appendFile(
-        state.filePath,
+      await appendFile(
+        filePath,
         `${JSON.stringify(record,)}\n`,
       );
     }
@@ -295,3 +290,4 @@ export function createFileSink(): Sink {
     write,
   };
 }
+//endregion File sink

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

@@ -9,25 +9,18 @@ import {
   expect,
   it,
 } from '@monochromatic-dev/module-test/ts';
+import type { LogRecord, } from '@monochromatic-dev/module-logger';
 import {
-  sinks,
-  type LogRecord,
-} from '@monochromatic-dev/module-logger';
-
-/**
- * Sink factories under test, read from the built artifact's `sinks` namespace.
- */
-const {
+  _findNodeModulesUp as findNodeModulesUp,
+  _NO_NODE_MODULES_FOUND as NO_NODE_MODULES_FOUND,
   createFileSink,
-  findNodeModulesUp,
-  NO_NODE_MODULES_FOUND,
-} = sinks;
+} from '@monochromatic-dev/module-logger/node';
 
 /**
- * Mock `stat` that always throws an ENOENT-like error, so `findNodeModulesUp`
- * walks the whole tree and exhausts without matching.
- *
- * @returns Never; always throws.
+ Mock `stat` that always throws an ENOENT-like error, so `findNodeModulesUp`
+ walks the whole tree and exhausts without matching.
+ 
+ @returns Never; always throws.
  */
 function statAlwaysMissing(): never {
   const error: NodeJS.ErrnoException = Object.assign(
@@ -38,9 +31,9 @@ function statAlwaysMissing(): never {
 }
 
 /**
- * Mock `stat` that always throws an unexpected permission error.
- *
- * @returns Never; always throws.
+ Mock `stat` that always throws an unexpected permission error.
+ 
+ @returns Never; always throws.
  */
 function statAlwaysDenied(): never {
   const error: NodeJS.ErrnoException = Object.assign(
@@ -51,11 +44,11 @@ function statAlwaysDenied(): never {
 }
 
 /**
- * Builds a LogRecord for write-path tests.
- *
- * @param message - Message body.
- *
- * @returns Record at a fixed timestamp.
+ Builds a LogRecord for write-path tests.
+ 
+ @param message - Message body.
+ 
+ @returns Record at a fixed timestamp.
  */
 function record({ message, }: { readonly message: string; },): LogRecord {
   return {
@@ -168,9 +161,9 @@ await describe({
     it({
       name: 'write before verify resolves without touching the filesystem',
       fn: async () => {
-        // Verification resolves the log path and caches `appendFile`; without
-        // it both stay unset, so write takes the unset-guard early return,
-        // resolving as a silent no-op rather than throwing or writing.
+        // Verification resolves the log path; without it the path stays
+        // unset, so write takes the unset-guard early return, resolving as a
+        // silent no-op rather than throwing or writing.
         const sink = createFileSink();
         await expect(
           sink.write(record({ message: 'before verify', },),),

package/src/sink/index.ts

@@ -1,11 +1,8 @@
+// Cross-platform factories only. The file sink lives behind the `./node`
+// subpath (`src/node.ts`) and the IndexedDB and OPFS sinks behind `./browser`
+// (`src/browser.ts`), so the root entry never pulls `node:fs` into the
+// neutral artifact nor browser-only storage code into the Node artifact.
 export { createConsoleSink, } from './console.ts';
-export {
-  createFileSink,
-  findNodeModulesUp,
-  NO_NODE_MODULES_FOUND,
-} from './file.ts';
-export { createIndexedDbSink, } from './indexed-db.ts';
 export { createLocalStorageSink, } from './local-storage.ts';
 export { createNoopSink, } from './noop.ts';
-export { createOpfsSink, } from './opfs.ts';
 export { createSessionStorageSink, } from './session-storage.ts';

package/src/sink/indexed-db-util.ts

@@ -1,32 +1,32 @@
 /**
- * Promise bridges for the event-based IndexedDB API.
- *
- * IndexedDB predates promises and signals completion only through `success`
- * and `error` events, so awaiting it requires wrapping each request and
- * transaction in a promise once, here, instead of scattering listener wiring
- * through the sink.
- *
- * @module
+ Promise bridges for the event-based IndexedDB API.
+ 
+ IndexedDB predates promises and signals completion only through `success`
+ and `error` events, so awaiting it requires wrapping each request and
+ transaction in a promise once, here, instead of scattering listener wiring
+ through the sink.
+ 
+ @module
  */
 
 /**
- * Resolves with an IndexedDB request's result once it succeeds, rejecting
- * with the request's error when it fails.
- *
- * @param request - Pending IndexedDB request.
- *
- * @returns Result the request produces.
- *
- * @throws DOMException - Whatever the backend attaches to a failed request.
- *
- * @mutates request - `request.addEventListener` registers success and error
- * listeners on the host-owned request, and `resolve` hands `request.result`,
- * a host-owned value, out to the awaiting caller.
- *
- * @example
- * ```ts
- * const key = await awaitRequest(store.add(batch));
- * ```
+ Resolves with an IndexedDB request's result once it succeeds, rejecting
+ with the request's error when it fails.
+ 
+ @param request - Pending IndexedDB request.
+ 
+ @returns Result the request produces.
+ 
+ @throws DOMException - Whatever the backend attaches to a failed request.
+ 
+ @mutates request - `request.addEventListener` registers success and error
+ listeners on the host-owned request, and `resolve` hands `request.result`,
+ a host-owned value, out to the awaiting caller.
+ 
+ @example
+ ```ts
+ const key = await awaitRequest(store.add(batch));
+ ```
  */
 export function awaitRequest<T,>(request: IDBRequest<T>,): Promise<T> {
   // oxlint-disable-next-line promise/avoid-new -- IndexedDB is event-based and exposes no promise API; a constructed promise is the only bridge to await it.
@@ -50,23 +50,23 @@ export function awaitRequest<T,>(request: IDBRequest<T>,): Promise<T> {
 }
 
 /**
- * Resolves once an IndexedDB transaction commits, rejecting when it errors or
- * aborts, so a caller can await durability of everything queued on it.
- *
- * @param transaction - Transaction whose settlement is awaited.
- *
- * @throws DOMException - Whatever the backend attaches to a failed or aborted
- * transaction.
- *
- * @mutates transaction - `transaction.addEventListener` registers complete,
- * error, and abort listeners on the host-owned transaction.
- *
- * @example
- * ```ts
- * const transaction = database.transaction('batch', 'readwrite');
- * transaction.objectStore('batch').add(batch);
- * await awaitTransaction(transaction);
- * ```
+ Resolves once an IndexedDB transaction commits, rejecting when it errors or
+ aborts, so a caller can await durability of everything queued on it.
+ 
+ @param transaction - Transaction whose settlement is awaited.
+ 
+ @throws DOMException - Whatever the backend attaches to a failed or aborted
+ transaction.
+ 
+ @mutates transaction - `transaction.addEventListener` registers complete,
+ error, and abort listeners on the host-owned transaction.
+ 
+ @example
+ ```ts
+ const transaction = database.transaction('batch', 'readwrite');
+ transaction.objectStore('batch').add(batch);
+ await awaitTransaction(transaction);
+ ```
  */
 export function awaitTransaction(transaction: IDBTransaction,): Promise<void> {
   // oxlint-disable-next-line promise/avoid-new -- IndexedDB is event-based and exposes no promise API; a constructed promise is the only bridge to await it.

package/src/sink/indexed-db.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('IndexedDB sink', () => {
   test.beforeEach(async ({ page, },) => {
     await page.goto('/',);
-    await page.waitForFunction(() => globalThis.moduleLogger !== undefined);
+    await page.waitForFunction(() => globalThis.moduleLoggerBrowser !== undefined);
   },);
 
   test('createIndexedDbSink exposes a callable verify', async ({ page, },) => {
     const typeofVerify = await page.evaluate(() => {
-      const { createIndexedDbSink, } = globalThis.moduleLogger.sinks;
+      const { createIndexedDbSink, } = globalThis.moduleLoggerBrowser;
       return typeof createIndexedDbSink().verify;
     },);
     expect(typeofVerify,).toBe('function',);
@@ -26,7 +26,7 @@ test.describe('IndexedDB sink', () => {
 
   test('verify detects availability', async ({ page, },) => {
     const result = await page.evaluate(async () => {
-      const { createIndexedDbSink, } = globalThis.moduleLogger.sinks;
+      const { createIndexedDbSink, } = globalThis.moduleLoggerBrowser;
       return createIndexedDbSink().verify();
     },);
     expect(result,).toBe(true,);
@@ -34,7 +34,7 @@ test.describe('IndexedDB sink', () => {
 
   test('a verified sink writes records across levels and message shapes', async ({ page, },) => {
     const allSucceeded = await page.evaluate(async () => {
-      const { createIndexedDbSink, } = globalThis.moduleLogger.sinks;
+      const { createIndexedDbSink, } = globalThis.moduleLoggerBrowser;
       const sink = createIndexedDbSink();
       await sink.verify();
       const levels = ['trace', 'debug', 'info', 'warn', 'error', 'fatal',] as const;
@@ -67,7 +67,7 @@ test.describe('IndexedDB sink', () => {
 
   test('a flushed batch is readable back out of the database as JSONL', async ({ page, },) => {
     const result = await page.evaluate(async () => {
-      const { createIndexedDbSink, } = globalThis.moduleLogger.sinks;
+      const { createIndexedDbSink, } = globalThis.moduleLoggerBrowser;
       const sink = createIndexedDbSink();
       await sink.verify();
 
@@ -126,7 +126,7 @@ test.describe('IndexedDB sink', () => {
   test('retention trims the store back to the cap, oldest first', async ({ page, },) => {
     test.setTimeout(120_000,);
     const result = await page.evaluate(async () => {
-      const { createIndexedDbSink, } = globalThis.moduleLogger.sinks;
+      const { createIndexedDbSink, } = globalThis.moduleLoggerBrowser;
       const sink = createIndexedDbSink();
       await sink.verify();