@monochromatic-dev/module-logger 0.1.0

package/src/sink/file.ts

@@ -0,0 +1,297 @@
+import type { stat as Stat, } from 'node:fs/promises';
+import type {
+  dirname as Dirname,
+  join as Join,
+} from 'node:path';
+
+import { reportLoggerInternalError, } from '../error-format.ts';
+
+import type { Sink, } from '../types.ts';
+
+/**
+ * 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 });
+ * ```
+ */
+export async function findNodeModulesUp(
+  {
+    cwd,
+    stat,
+    dirname,
+    join,
+    reportError = reportLoggerInternalError,
+  }: {
+    readonly cwd: string;
+    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.
+   */
+  const candidate = join(
+    cwd,
+    'node_modules',
+  );
+  try {
+    /**
+     * Stat result for `candidate`; only directories count as a hit, guarding against a sibling file also named `node_modules`.
+     */
+    const entry = await stat(candidate,);
+    if (entry.isDirectory())
+      return candidate;
+  }
+  catch (error: unknown) {
+    // Missing candidate is expected while walking ancestors; only unexpected stat failures are logger faults.
+    if (!(Error.isError(error,)
+      && ('code' in error)
+      && (error.code === 'ENOENT'))) {
+      reportError({
+        context: `node_modules candidate ${candidate} unavailable during file sink search`,
+        error,
+      },);
+    }
+  }
+  /**
+   * Parent directory used by the next recursive step; equal to `cwd` only at the filesystem root, which terminates the walk.
+   */
+  const parent = dirname(cwd,);
+  if (parent === cwd)
+    return NO_NODE_MODULES_FOUND;
+  return await findNodeModulesUp({
+    cwd: parent,
+    stat,
+    dirname,
+    join,
+    reportError,
+  },);
+}
+
+/**
+ * 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();
+ * ```
+ */
+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.
+   */
+  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.
+   */
+  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).
+       */
+      const nodeModulesDir = await findNodeModulesUp({
+        cwd: process.cwd(),
+        stat: fs.stat,
+        dirname,
+        join,
+      },);
+
+      if (nodeModulesDir === NO_NODE_MODULES_FOUND)
+        // Unexpected in a Node environment: the process is running JS, which
+        // almost always means there is a node_modules upward. Marking the sink
+        // unavailable (rather than creating one at a stray cwd) keeps stray log
+        // directories out of build output.
+        return false;
+
+      /**
+       * Directory under the chosen `node_modules` where every monochromatic log file lands.
+       */
+      const LOG_DIR = join(
+        nodeModulesDir,
+        '.monochromatic',
+      );
+      await fs.mkdir(
+        LOG_DIR,
+        { recursive: true, },
+      );
+
+      /**
+       * 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_DIR,
+        `${timestamp}.log.jsonl`,
+      );
+
+      // Verify by writing and reading test data.
+      /**
+       * 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,
+        testData,
+      );
+      /**
+       * 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,
+        'utf8',
+      );
+      return content.includes('"test":true',);
+    }
+    catch (error: unknown) {
+      reportLoggerInternalError({
+        context: 'file sink verification failed',
+        error,
+      },);
+      return false;
+    }
+  }
+
+  /**
+   * 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
+      !== undefined)
+      return state.verifyPromise;
+
+    state.verifyPromise = runVerify();
+    return state.verifyPromise;
+  }
+
+  /**
+   * 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))
+      return;
+
+    try {
+      await state.appendFile(
+        state.filePath,
+        `${JSON.stringify(record,)}\n`,
+      );
+    }
+    catch (error: unknown) {
+      reportLoggerInternalError({
+        context: 'file sink record append failed',
+        error,
+      },);
+    }
+  }
+
+  return {
+    verify,
+    write,
+  };
+}

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

@@ -0,0 +1,202 @@
+import { stat, } from 'node:fs/promises';
+import {
+  dirname,
+  join,
+} from 'node:path';
+
+import {
+  describe,
+  expect,
+  it,
+} from '@monochromatic-dev/module-test/ts';
+import {
+  sinks,
+  type LogRecord,
+} from '@monochromatic-dev/module-logger';
+
+/**
+ * Sink factories under test, read from the built artifact's `sinks` namespace.
+ */
+const {
+  createFileSink,
+  findNodeModulesUp,
+  NO_NODE_MODULES_FOUND,
+} = sinks;
+
+/**
+ * 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(
+    new Error('ENOENT',),
+    { code: 'ENOENT', },
+  );
+  throw error;
+}
+
+/**
+ * Mock `stat` that always throws an unexpected permission error.
+ *
+ * @returns Never; always throws.
+ */
+function statAlwaysDenied(): never {
+  const error: NodeJS.ErrnoException = Object.assign(
+    new Error('EACCES',),
+    { code: 'EACCES', },
+  );
+  throw error;
+}
+
+/**
+ * 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 {
+    level: 'info',
+    message,
+    timestamp: 0,
+  };
+}
+
+await describe({
+  name: 'file sink',
+  children: [
+    it({
+      name: 'exposes callable verify and write methods',
+      fn: async () => {
+        const sink = createFileSink();
+        expect(typeof sink.verify,).toBe('function',);
+        expect(typeof sink.write,).toBe('function',);
+      },
+    },),
+
+    it({
+      name: 'verify resolves a boolean',
+      fn: async () => {
+        const resolved = await createFileSink().verify();
+        expect(typeof resolved,).toBe('boolean',);
+      },
+    },),
+
+    it({
+      name: 'verify reports availability when running in a package with ancestor node_modules',
+      fn: async () => {
+        // Tests run from within the monorepo, so an ancestor node_modules
+        // always exists. Availability proves find-up located it AND that
+        // mkdir/appendFile/readFile all succeeded.
+        expect(await createFileSink().verify(),).toBe(true,);
+      },
+    },),
+
+    it({
+      name: 'concurrent verify calls on one sink share a single in-flight promise',
+      fn: async () => {
+        // Regression guard for the race that used to return false to late
+        // callers. The memo now lives in the instance closure, not a module
+        // global, so a fresh sink exercises it cleanly.
+        const sink = createFileSink();
+        const [a, b, c,] = await Promise.all([
+          sink.verify(),
+          sink.verify(),
+          sink.verify(),
+        ],);
+        expect(a,).toBe(b,);
+        expect(b,).toBe(c,);
+      },
+    },),
+
+    it({
+      name: 'findNodeModulesUp finds the nearest ancestor node_modules',
+      fn: async () => {
+        const result = await findNodeModulesUp({
+          cwd: import.meta.dirname,
+          stat,
+          dirname,
+          join,
+        },);
+        expect(typeof result,).toBe('string',);
+        if ((typeof result) === 'string')
+          expect(result.endsWith('node_modules',),).toBe(true,);
+      },
+    },),
+
+    it({
+      name: 'findNodeModulesUp keeps expected missing candidates silent',
+      fn: async () => {
+        /** Unexpected faults reported during expected missing-path walk. */
+        const reports: unknown[] = [];
+        /** Exhausted ancestor result. */
+        const result = await findNodeModulesUp({
+          cwd: import.meta.dirname,
+          stat: statAlwaysMissing as unknown as typeof stat,
+          dirname,
+          join,
+          reportError: function collectUnexpectedReport(report,) {
+            reports.push(report,);
+          },
+        },);
+        expect(result,).toBe(NO_NODE_MODULES_FOUND,);
+        expect(reports,).toEqual([],);
+      },
+    },),
+
+    it({
+      name: 'findNodeModulesUp reports unexpected stat failures',
+      fn: async () => {
+        /** Unexpected faults reported during denied-path walk. */
+        const reports: unknown[] = [];
+        await findNodeModulesUp({
+          cwd: import.meta.dirname,
+          stat: statAlwaysDenied as unknown as typeof stat,
+          dirname,
+          join,
+          reportError: function collectUnexpectedReport(report,) {
+            reports.push(report,);
+          },
+        },);
+        expect(reports.length > 0,).toBe(true,);
+      },
+    },),
+
+    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.
+        const sink = createFileSink();
+        await expect(
+          sink.write(record({ message: 'before verify', },),),
+        )
+          .resolves
+          .toBeUndefined();
+      },
+    },),
+
+    it({
+      name: 'a verified sink accepts records across levels and message shapes',
+      fn: async () => {
+        const sink = createFileSink();
+        await sink.verify();
+
+        const messages = [
+          'plain message',
+          'Hello 世界 🌍',
+          '',
+          '{"key": "value", "nested": {"a": 1}}',
+          'line1\nline2\nline3',
+        ];
+        for (const message of messages)
+          // oxlint-disable-next-line no-await-in-loop -- sequential appends keep file order deterministic
+          await sink.write(record({ message, },),);
+      },
+    },),
+  ],
+},);

package/src/sink/index.ts

@@ -0,0 +1,11 @@
+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

@@ -0,0 +1,96 @@
+/**
+ * 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));
+ * ```
+ */
+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.
+  return new Promise(function bridgeRequest(
+    resolve,
+    reject,
+  ) {
+    request.addEventListener(
+      'success',
+      function resolveResult(): void {
+        resolve(request.result,);
+      },
+    );
+    request.addEventListener(
+      'error',
+      function rejectError(): void {
+        reject(request.error ?? new Error('IndexedDB request failed without an error object',),);
+      },
+    );
+  },);
+}
+
+/**
+ * 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.
+  return new Promise(function bridgeTransaction(
+    resolve,
+    reject,
+  ) {
+    transaction.addEventListener(
+      'complete',
+      function resolveCommit(): void {
+        resolve();
+      },
+    );
+    transaction.addEventListener(
+      'error',
+      function rejectError(): void {
+        reject(transaction.error ?? new Error('IndexedDB transaction failed without an error object',),);
+      },
+    );
+    transaction.addEventListener(
+      'abort',
+      function rejectAbort(): void {
+        reject(transaction.error ?? new Error('IndexedDB transaction aborted without an error object',),);
+      },
+    );
+  },);
+}