@monochromatic-dev/module-logger 0.1.0 → 0.3.0

package/src/sink/web-storage-quota-error.ts

@@ -1,16 +1,16 @@
 /**
- * Quota-overflow recognition shared by the web storage persistence engines.
- *
- * @module
+ Quota-overflow recognition shared by the web storage persistence engines.
+ 
+ @module
  */
 
 /**
- * Error `name` values engines raise for a storage quota overflow: the DOM
- * standard name every current browser and Node web storage use, plus Firefox's
- * legacy alias. Quota overflow is matched by `name` rather than by class or
- * numeric `code` because the concrete type differs by engine (a `DOMException`
- * in Chromium and Node, a differently-branded object historically in Firefox),
- * while the standard name is stable across them.
+ Error `name` values engines raise for a storage quota overflow: the DOM
+ standard name every current browser and Node web storage use, plus Firefox's
+ legacy alias. Quota overflow is matched by `name` rather than by class or
+ numeric `code` because the concrete type differs by engine (a `DOMException`
+ in Chromium and Node, a differently-branded object historically in Firefox),
+ while the standard name is stable across them.
  */
 const QUOTA_EXCEEDED_NAMES: ReadonlySet<string> = new Set([
   'QuotaExceededError',
@@ -18,19 +18,19 @@ const QUOTA_EXCEEDED_NAMES: ReadonlySet<string> = new Set([
 ],);
 
 /**
- * Reports whether a caught `setItem` value is a storage quota overflow, so
- * eviction reclaims space only for a full store and never for an unrelated
- * write fault such as a disabled-storage `SecurityError`.
- *
- * @param error - Caught value from a `setItem` failure.
- *
- * @returns Whether `error` names a quota overflow.
- *
- * @example
- * ```ts
- * try { sessionStorage.setItem(k, v); }
- * catch (error: unknown) { if (isQuotaExceededError(error)) evictOldest(); }
- * ```
+ Reports whether a caught `setItem` value is a storage quota overflow, so
+ eviction reclaims space only for a full store and never for an unrelated
+ write fault such as a disabled-storage `SecurityError`.
+ 
+ @param error - Caught value from a `setItem` failure.
+ 
+ @returns Whether `error` names a quota overflow.
+ 
+ @example
+ ```ts
+ try { sessionStorage.setItem(k, v); }
+ catch (error: unknown) { if (isQuotaExceededError(error)) evictOldest(); }
+ ```
  */
 export function isQuotaExceededError(error: unknown,): boolean {
   return (

package/src/sink/web-storage-quota-error.unit.test.ts

@@ -14,7 +14,7 @@ await describe({
       name: 'recognizes the standard DOMException name',
       fn: async () => {
         /**
-         * Overflow shaped exactly as current engines raise it.
+         Overflow shaped exactly as current engines raise it.
          */
         const overflow = new DOMException('full', 'QuotaExceededError',);
         expect(isQuotaExceededError(overflow,),)
@@ -34,7 +34,7 @@ await describe({
       name: 'rejects a plain Error whose message merely mentions quota',
       fn: async () => {
         /**
-         * Non-quota failure that only talks about quota in prose.
+         Non-quota failure that only talks about quota in prose.
          */
         const impostor = new Error('quota exceeded',);
         expect(isQuotaExceededError(impostor,),)

package/src/sink/web-storage-runtime.ts

@@ -1,35 +1,35 @@
 /**
- * Shared host-runtime detection for web storage quota heuristics.
- *
- * The Web Storage API exposes no way to read a store's quota, so the
- * per-storage-area quota modules pair this detection with their own tables of
- * measured defaults. Detection is by host global rather than user-agent
- * string: Deno and Bun both shim `process` with a Node-compatible
- * `process.versions.node`, so their own globals are tested before the Node
- * check to avoid misclassifying them.
- *
- * @module
+ Shared host-runtime detection for web storage quota heuristics.
+ 
+ The Web Storage API exposes no way to read a store's quota, so the
+ per-storage-area quota modules pair this detection with their own tables of
+ measured defaults. Detection is by host global rather than user-agent
+ string: Deno and Bun both shim `process` with a Node-compatible
+ `process.versions.node`, so their own globals are tested before the Node
+ check to avoid misclassifying them.
+ 
+ @module
  */
 
 /**
- * Host runtimes distinguishable by global probes, plus `unknown` for
- * everything else so callers fall back to uncapped reactive eviction.
+ Host runtimes distinguishable by global probes, plus `unknown` for
+ everything else so callers fall back to uncapped reactive eviction.
  */
 export type WebStorageRuntime = 'browser' | 'bun' | 'deno' | 'node' | 'unknown';
 
 /**
- * Detects the current host runtime for web storage quota lookups.
- *
- * A `node` result also covers Node-embedding hosts such as Electron, whose
- * renderer exposes `process.versions.node` alongside a DOM; callers that need
- * to tell those apart check `'document' in globalThis` themselves.
- *
- * @returns Detected runtime, or `unknown` when no marker global matches.
- *
- * @example
- * ```ts
- * const quota = RUNTIME_QUOTA_CHARS[detectWebStorageRuntime()];
- * ```
+ Detects the current host runtime for web storage quota lookups.
+ 
+ A `node` result also covers Node-embedding hosts such as Electron, whose
+ renderer exposes `process.versions.node` alongside a DOM; callers that need
+ to tell those apart check `'document' in globalThis` themselves.
+ 
+ @returns Detected runtime, or `unknown` when no marker global matches.
+ 
+ @example
+ ```ts
+ const quota = RUNTIME_QUOTA_CHARS[detectWebStorageRuntime()];
+ ```
  */
 export function detectWebStorageRuntime(): WebStorageRuntime {
   if ('Deno' in globalThis)

package/src/startup.unit.test.ts

@@ -52,12 +52,12 @@ type ProbeResult = {
 };
 
 /**
- * Builds a throwaway project root with `node_modules` so the file sink chooses
- * an isolated `node_modules/.monochromatic` log directory.
- *
- * @param logLine - Logger call that the generated probe should execute.
- *
- * @returns Temporary project handle removed by `await using`.
+ Builds a throwaway project root with `node_modules` so the file sink chooses
+ an isolated `node_modules/.monochromatic` log directory.
+ 
+ @param logLine - Logger call that the generated probe should execute.
+ 
+ @returns Temporary project handle removed by `await using`.
  */
 async function createTempProject(
   { logLine, }: { readonly logLine: string; },
@@ -99,13 +99,13 @@ async function createTempProject(
 }
 
 /**
- * Runs a probe script in its temporary project root.
- *
- * @param cwd - Project root used as `process.cwd()` by the file sink.
- * @param env - Environment overrides applied to the probe process.
- * @param scriptPath - Absolute path to the probe script.
- *
- * @returns Captured stdout, stderr, and exit code.
+ Runs a probe script in its temporary project root.
+ 
+ @param cwd - Project root used as `process.cwd()` by the file sink.
+ @param env - Environment overrides applied to the probe process.
+ @param scriptPath - Absolute path to the probe script.
+ 
+ @returns Captured stdout, stderr, and exit code.
  */
 async function runProbe(
   {
@@ -151,11 +151,11 @@ async function runProbe(
 }
 
 /**
- * Reads the single JSONL file created by the probe's file sink.
- *
- * @param projectPath - Temporary project root containing `node_modules`.
- *
- * @returns Log file contents.
+ Reads the single JSONL file created by the probe's file sink.
+ 
+ @param projectPath - Temporary project root containing `node_modules`.
+ 
+ @returns Log file contents.
  */
 async function readOnlyLogContent({ projectPath, }: { readonly projectPath: string; },): Promise<string> {
   const logDir = join(

package/src/tagged.ts

@@ -2,40 +2,40 @@ import { logger as defaultLogger, } from './logger.ts';
 import type { Logger, } from './types.ts';
 
 /**
- * Wraps a logger so every message is prefixed with `[tag] `.
- * Callers typically pass `myFn.name` as tag to keep prefixes
- * in sync with refactors.
- *
- * @param tag - Prefix string inserted before each message
- *
- * @param l - Base logger to wrap; defaults to the module-level {@link logger}
- *   singleton
- *
- * @returns Logger whose methods prepend `[tag] ` to every message
- *
- * @example
- * ```ts
- * import { tagged } from '\@monochromatic-dev/module-logger/tagged';
- *
- * function handleRequest({ l }: { l: Logger }): void {
- *   l.info('received');
- * }
- *
- * handleRequest({ l: tagged({ tag: handleRequest.name }) });
- * // logs: [handleRequest] received
- * ```
- *
- * @example
- * ```ts
- * // Composing tags: the outermost wrap (`l2` here) prepends to the message
- * // last, so its tag ends up rightmost. The innermost wrap (`l1`) hits the
- * // underlying logger first, so its tag is leftmost. The chain reads
- * // root-first: outer wrap = inner tag position.
- * const l1 = tagged({ tag: 'http' });
- * const l2 = tagged({ tag: 'retry', l: l1 });
- * l2.info('attempt 3');
- * // logs: [http] [retry] attempt 3
- * ```
+ Wraps a logger so every message is prefixed with `[tag] `.
+ Callers typically pass `myFn.name` as tag to keep prefixes
+ in sync with refactors.
+ 
+ @param tag - Prefix string inserted before each message
+ 
+ @param l - Base logger to wrap; defaults to the module-level {@link logger}
+   singleton
+ 
+ @returns Logger whose methods prepend `[tag] ` to every message
+ 
+ @example
+ ```ts
+ import { tagged } from '\@monochromatic-dev/module-logger/tagged';
+ 
+ function handleRequest({ l }: { l: Logger }): void {
+   l.info('received');
+ }
+ 
+ handleRequest({ l: tagged({ tag: handleRequest.name }) });
+ // logs: [handleRequest] received
+ ```
+ 
+ @example
+ ```ts
+ // Composing tags: the outermost wrap (`l2` here) prepends to the message
+ // last, so its tag ends up rightmost. The innermost wrap (`l1`) hits the
+ // underlying logger first, so its tag is leftmost. The chain reads
+ // root-first: outer wrap = inner tag position.
+ const l1 = tagged({ tag: 'http' });
+ const l2 = tagged({ tag: 'retry', l: l1 });
+ l2.info('attempt 3');
+ // logs: [http] [retry] attempt 3
+ ```
  */
 export function tagged({
   tag,
@@ -45,7 +45,7 @@ export function tagged({
   readonly tag: string;
 },): Logger {
   /**
-   * Bracketed tag prepended to every message; built once so each log call does one concatenation.
+   Bracketed tag prepended to every message; built once so each log call does one concatenation.
    */
   const prefix = `[${tag}] `;
   return {

package/src/tagged.unit.test.ts

@@ -10,8 +10,8 @@ import {
 } from '@monochromatic-dev/module-logger';
 
 /**
- * Every log level paired with the message body the all-levels test sends
- * through each, so the assertion can be built from one source of truth.
+ Every log level paired with the message body the all-levels test sends
+ through each, so the assertion can be built from one source of truth.
  */
 const LEVEL_MESSAGES: readonly { readonly level: Level; readonly message: string; }[] = [
   {
@@ -41,12 +41,12 @@ const LEVEL_MESSAGES: readonly { readonly level: Level; readonly message: string
 ];
 
 /**
- * Builds a stub logger whose methods record the messages they receive
- * and whose `flush` is a trivial resolved promise. Used to verify the
- * tagged wrapper's message prefixing and `flush` forwarding without
- * touching the default multi-sink singleton.
- *
- * @returns Object containing the stub logger and the recorded message list.
+ Builds a stub logger whose methods record the messages they receive
+ and whose `flush` is a trivial resolved promise. Used to verify the
+ tagged wrapper's message prefixing and `flush` forwarding without
+ touching the default multi-sink singleton.
+ 
+ @returns Object containing the stub logger and the recorded message list.
  */
 function createStubLogger(): {
   l: Logger;

package/src/types.ts

@@ -1,10 +1,10 @@
 /**
- * Log severity levels ordered from least to most severe.
+ Log severity levels ordered from least to most severe.
  */
 export type Level = 'debug' | 'error' | 'fatal' | 'info' | 'trace' | 'warn';
 
 /**
- * Structured log record written to sinks.
+ Structured log record written to sinks.
  */
 export type LogRecord = {
   readonly level: Level;
@@ -13,47 +13,47 @@ export type LogRecord = {
 };
 
 /**
- * Optional drain hook for sinks that buffer records internally.
- * Called via logger-level {@link Logger.flush} to force buffered work
- * through before a process exit, critical error boundary, or assertion.
- *
- * Always async: sinks whose drain is synchronous return an
- * already-resolved promise so callers `await` uniformly. A `void` arm is
- * not used; under the `no-optional-escape` rule `T | void` is a banned
- * fake-optional encoding, and there is no real synchronous value to carry.
+ Optional drain hook for sinks that buffer records internally.
+ Called via logger-level {@link Logger.flush} to force buffered work
+ through before a process exit, critical error boundary, or assertion.
+ 
+ Always async: sinks whose drain is synchronous return an
+ already-resolved promise so callers `await` uniformly. A `void` arm is
+ not used; under the `no-optional-escape` rule `T | void` is a banned
+ fake-optional encoding, and there is no real synchronous value to carry.
  */
 export type SinkFlush = () => Promise<void>;
 
 /**
- * Verification function that checks if a sink backend is available.
- * May run setup side effects (resolving a log path, opening a writable
- * stream) and reports whether the backend is usable. A sink whose
- * verification resolves `false` (or rejects) is dropped by the logger and
- * receives no further records.
- *
- * Always async, matching `write` and `flush`: a synchronous check returns an
- * already-resolved promise (`Promise.resolve(check)`) so the logger awaits
- * verification uniformly with no sync/async branch.
+ Verification function that checks if a sink backend is available.
+ May run setup side effects (resolving a log path, opening a writable
+ stream) and reports whether the backend is usable. A sink whose
+ verification resolves `false` (or rejects) is dropped by the logger and
+ receives no further records.
+ 
+ Always async, matching `write` and `flush`: a synchronous check returns an
+ already-resolved promise (`Promise.resolve(check)`) so the logger awaits
+ verification uniformly with no sync/async branch.
  */
 export type Verify = () => Promise<boolean>;
 
 /**
- * Sink that receives log records. A sink is a self-describing adapter: it
- * carries everything the logger must know to use it, namely how to
- * `verify` its backend is available, how to `write` a record, and
- * optionally how to `flush` buffered work. Holding `verify` on the sink
- * (rather than as a sibling export the logger pairs by hand) lets the
- * logger treat a registry as a plain `Sink[]` and lets a test supply one
- * self-contained fake.
- *
- * Sinks that buffer records (e.g. microtask-batched console) may
- * expose a `flush` hook so callers can force emission on demand.
- *
- * `write` is always async: a synchronous sink does its work eagerly and
- * returns an already-resolved promise, so the logger observes a uniform
- * `Promise<void>`. A rejected write is handled per sink and does not
- * disable the backend; only a failed `verify` drops a sink. A `void` arm
- * is not used, for the reason stated on {@link SinkFlush}.
+ Sink that receives log records. A sink is a self-describing adapter: it
+ carries everything the logger must know to use it, namely how to
+ `verify` its backend is available, how to `write` a record, and
+ optionally how to `flush` buffered work. Holding `verify` on the sink
+ (rather than as a sibling export the logger pairs by hand) lets the
+ logger treat a registry as a plain `Sink[]` and lets a test supply one
+ self-contained fake.
+ 
+ Sinks that buffer records (e.g. microtask-batched console) may
+ expose a `flush` hook so callers can force emission on demand.
+ 
+ `write` is always async: a synchronous sink does its work eagerly and
+ returns an already-resolved promise, so the logger observes a uniform
+ `Promise<void>`. A rejected write is handled per sink and does not
+ disable the backend; only a failed `verify` drops a sink. A `void` arm
+ is not used, for the reason stated on {@link SinkFlush}.
  */
 export type Sink = {
   readonly flush?: SinkFlush;
@@ -62,10 +62,10 @@ export type Sink = {
 };
 
 /**
- * Logger interface with 6 log levels plus `flush` for startup and sink drains.
- * `flush()` resolves once startup verification has completed, tracked sink
- * writes have settled, and every available sink's own {@link SinkFlush} hook
- * has settled. Safe to call even when no sink buffers.
+ Logger interface with 6 log levels plus `flush` for startup and sink drains.
+ `flush()` resolves once startup verification has completed, tracked sink
+ writes have settled, and every available sink's own {@link SinkFlush} hook
+ has settled. Safe to call even when no sink buffers.
  */
 export type Logger = {
   readonly debug: (message: string,) => void;