@monochromatic-dev/module-logger 0.1.0

package/LICENSES/LGPL-3.0-or-later.txt

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

package/README.md

@@ -0,0 +1,404 @@
+# module-logger
+
+Zero-config multi-sink logger with tagged composition.
+Works immediately at import:
+ auto-discovers available backends for the current runtime,
+and records emitted while async backend verification is still pending replay to those
+backends as soon as they verify.
+ Consumers do not await `initPromise` before logging.
+
+## Usage
+
+```ts
+import { tagged, } from '@monochromatic-dev/module-logger';
+
+const l = tagged({ tag: 'http', },);
+l.info('server started on port 3000',);
+// console output: [info] [2026-03-11T...] [http] server started on port 3000
+```
+
+### Composing tags
+
+Pass a parent logger via the `l` parameter to build hierarchical prefixes:
+
+```ts
+const l = tagged({ tag: 'http', },);
+const rl = tagged({ tag: 'retry', l, },);
+rl.warn('attempt 3 failed',);
+// [warn] [...] [http] [retry] attempt 3 failed
+```
+
+Composed tags render root-first because each wrapper prepends before delegating to its parent logger.
+
+Convention:
+ use `myFn.name` as the tag so prefixes stay in sync with refactors.
+
+```ts
+function handleRequest({ l, }: { l: Logger; },): void {
+  const rl = tagged({ tag: handleRequest.name, l, },);
+  rl.info('received',);
+}
+```
+
+### Default logger (no tags)
+
+Import the singleton directly when tags are not needed:
+
+```ts
+import { logger, } from '@monochromatic-dev/module-logger';
+
+logger.error('unexpected shutdown',);
+```
+
+## Runtime support
+
+Node 24 or newer (the build calls `Error.isError`),
+ plus current browsers,
+ Deno,
+ and Bun for the sinks whose `verify` finds a backend there.
+The published package exposes the built artifact only.
+The `/ts` source subpath used inside this workspace is stripped at publish time,
+ because Node refuses `.ts` files under `node_modules`.
+
+## Log levels
+
+Six levels,
+ each mapping to a dedicated method:
+ `trace`,
+ `debug`,
+ `info`,
+ `warn`,
+ `error`,
+ `fatal`.
+
+All methods accept a single `string` argument.
+The caller owns serialization;
+ template literals cover the common case
+and keep the logger free of stringify opinions.
+
+```ts
+l.info(`status ${code} for ${url}`,);
+```
+
+The console sink silences `debug` and `trace` by default in non-browser environments.
+Set `MONOCHROMATIC_VERBOSE=true` or pass `--verbose` to enable them.
+In browsers,
+ verbose mode is enabled automatically because DevTools
+already provides its own log-level filtering.
+
+## Sinks
+
+The default logger writes to **all** available sinks simultaneously.
+Availability is verified at module load;
+ records emitted while an async sink is
+still being verified are replayed to that sink when it becomes available.
+
+- **console**:
+   formats as `[level] [ISO timestamp] message`;
+  maps levels to corresponding `console.*` methods,
+  except `debug` writes to `process.stderr` when `process.stderr.write` is available
+- **file**:
+   Node.
+  js only;
+   walks up from `process.cwd()` to the nearest
+  ancestor `node_modules/`,
+   then appends JSONL records to
+  `<that dir>/node_modules/.monochromatic/{timestamp}.log.jsonl` via
+  `node:fs/promises`.
+   When no ancestor `node_modules/` exists,
+   the sink
+  is marked unavailable rather than creating one at cwd;
+   this prevents
+  stray log directories from landing inside build output or other
+  non-project trees when a script is invoked from an unexpected cwd
+- **IndexedDB**:
+   browser only;
+   buffers records through the same shared policy and flush triggers as the
+  sessionStorage sink and stores each newline-joined JSONL batch as one
+  string value per transaction in the `monochromatic.log` database
+  (`batch` store,
+   auto-incremented keys,
+   so concurrent tabs serialize
+  without any key scheme);
+   records are readable the moment their transaction settles,
+   DevTools
+  Application tab included,
+   and survive tab close and browser restart;
+   retention trims oldest-first past 2048 stored batches;
+   `logger.flush()` settles every issued batch transaction
+- **OPFS** (exported but not a default):
+   browser only;
+   buffers records and appends them to the Origin Private File System as
+  newline-joined JSONL batches,
+   one queued stream write per batch,
+   under
+  the same flush triggers as the sessionStorage sink;
+   keeps a `FileSystemWritableFileStream` open for the session,
+   and `logger.flush()` settles every issued batch write;
+   staged stream content only becomes the file on a close a crash never
+  performs,
+   which is why the IndexedDB sink holds the default
+  persistent-browser slot instead (see `DECISIONS.md`)
+- **sessionStorage**:
+   available wherever `globalThis.sessionStorage` exists (browsers,
+   Node,
+   Deno);
+   buffers records and stores them as newline-joined JSONL batches under
+  `monochromatic.log.{n}` keys with an auto-incrementing counter;
+   one uniform write path on every runtime flushes a batch when it reaches
+  32 KiB,
+   when a record's severity is `warn` or worse,
+   after 250 ms of quiet,
+  on `pagehide`/document-hidden where those events exist,
+   and on
+  `logger.flush()`;
+   caps its own footprint at half the runtime's default sessionStorage quota
+  (a measured per-runtime heuristic:
+   5 MiB on Node and the browser engines,
+  10 MiB on Deno),
+   evicting its oldest batches first and reclaiming further space reactively
+  if the real store still overflows
+- **localStorage**:
+   available wherever `globalThis.localStorage` round-trips (browsers,
+   Deno,
+   Node launched with `--localstorage-file`;
+   flagless Node skips the probe silently);
+   buffers through the same shared policy and flush triggers as the
+  sessionStorage sink,
+   but stores each batch under a run-scoped key
+  (`monochromatic.log.{stamp}.{nonce}.{index}`) because localStorage is shared
+  across tabs and survives restarts;
+   adopts entries left by earlier runs and evicts oldest-first,
+   capping the combined footprint at half the runtime's default localStorage
+  quota (5 MiB on Node and the browser engines,
+   just under 10 MiB on Deno);
+   the one web storage sink whose records remain inspectable after tab close
+  or a full browser restart
+- **noop**:
+   discards all records;
+   a stand-in that disables logging without removing log calls
+
+Each sink is a factory,
+ `createConsoleSink()`,
+ `createFileSink()`,
+ `createIndexedDbSink()`,
+ `createOpfsSink()`,
+`createSessionStorageSink()`,
+ `createLocalStorageSink()`,
+ and `createNoopSink()`,
+ exported under the `sinks` namespace.
+A sink instance keeps its own buffers,
+ streams,
+ and counters,
+ so independent loggers never
+share state.
+
+Async sinks are fire-and-forget;
+ the log call never blocks the caller.
+Call `logger.flush()` before assertions or process shutdown to wait for startup
+verification,
+ pending sink writes,
+ and sink-owned flush hooks.
+A sink is dropped only when its `verify` reports the backend unavailable (resolves
+`false` or rejects);
+ a sink whose `flush` hook rejects is also dropped.
+Individual `write` failures are the sink's own concern and do not disable the backend,
+so one transient I/O hiccup never silently kills a sink for the rest of the run.
+
+## Console output safety
+
+Log text can carry attacker-influenced content,
+ and a terminal treats control characters as commands (clear screen,
+ set title,
+ move the cursor,
+ write the clipboard).
+The console sink renders every C0 control except newline and tab,
+ `DEL`,
+ and every C1 control as a `\uXXXX` escape before the text reaches `console.*` or `process.stderr`,
+ so the attempted sequence stays visible but inert.
+Newlines and tabs pass through because multi-line messages are core.
+The JSONL sinks need no such step:
+ `JSON.stringify` already escapes control characters.
+
+## Log record format
+
+Every sink receives a `LogRecord`:
+
+```ts
+type LogRecord = {
+  level: Level; // 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal'
+  message: string;
+  timestamp: number; // Date.now()
+};
+```
+
+File,
+ IndexedDB,
+ OPFS,
+ sessionStorage,
+ and localStorage sinks write records as one JSON object per line (JSONL).
+
+## Error handling
+
+- `initPromise` resolves after eager verification and startup replay;
+   consumers do not await it before logging
+- `logger.flush()` awaits startup verification,
+   pending sink writes,
+   and sink-owned flush hooks,
+   all under one deadline (`flushDeadlineMs`,
+   default `DEFAULT_FLUSH_DEADLINE_MS`,
+   5000 ms).
+   When the deadline elapses the logger reports one `console.warn` breadcrumb,
+   drops the in-flight writes from its view (sinks expose no cancellation,
+   so the work continues in the background),
+   and resolves,
+   so a wedged backend cannot hang a shutdown
+- Throws at log time once initialization has completed with no available backend.
+   The console sink verifies wherever `console` and `queueMicrotask` exist,
+   so this is reachable only through `createLogger` with sinks that all fail verification
+- A sink is dropped when its `verify` reports unavailable (or its flush hook rejects);
+   remaining sinks continue
+- Individual `write` failures are handled per sink and do not disable the backend
+
+## Custom loggers
+
+The default `logger` is `createLogger` applied to the default sink set,
+ and it stays
+zero-config.
+ `createLogger` is also exported for building a logger over an explicit sink
+list,
+ for example to write to a fixed subset of backends or to inject a fake in tests.
+
+```ts
+import { createLogger, sinks, } from '@monochromatic-dev/module-logger';
+
+const { logger, initPromise, } = createLogger({ sinks: [sinks.createNoopSink()], },);
+logger.info('goes nowhere');
+await initPromise; // optional; flush() awaits it internally
+```
+
+Raise the flush deadline for a slow but working backend,
+ such as a network filesystem:
+
+```ts
+import { createLogger, sinks, } from '@monochromatic-dev/module-logger';
+
+const { logger, } = createLogger({
+  sinks: [sinks.createFileSink(),],
+  flushDeadlineMs: 30_000,
+},);
+```
+
+A custom sink is any object satisfying the `Sink` interface,
+ a single self-describing
+adapter carrying `verify`,
+ `write`,
+ and an optional `flush`:
+
+```ts
+import type { LogRecord, Sink, } from '@monochromatic-dev/module-logger';
+
+function createArraySink(): { records: LogRecord[]; sink: Sink; } {
+  const records: LogRecord[] = [];
+  const sink: Sink = {
+    verify: () => Promise.resolve(true),
+    write: (record) => {
+      records.push(record);
+      return Promise.resolve();
+    },
+  };
+  return { records, sink, };
+}
+```
+
+`verify`,
+ `write`,
+ and `flush` are all async (returning `Promise`) so the logger awaits
+them uniformly.
+
+## Design decisions
+
+See [DECISIONS.md](DECISIONS.md) for rationale on:
+
+- No sub-logger hierarchy;
+   per-component filtering is a log viewer problem
+- String-only messages;
+   callers own serialization;
+   no auto-stringify
+- Sinks are self-describing factories;
+   the logger owns availability
+- Write failures do not disable a sink;
+   only verify failure does
+- localStorage and IndexedDB sink designs and measurements
+- Console output neutralizes control characters
+- `flush()` has a deadline
+
+## Source files
+
+- `src/types.ts`:
+   `Logger`,
+   `LogRecord`,
+   `Sink`,
+   `SinkFlush`,
+   `Verify`,
+   `Level` type definitions
+- `src/create-logger.ts`:
+   `createLogger({ sinks })` orchestration (verify,
+   startup replay,
+   flush)
+- `src/logger.ts`:
+   default singleton built by applying `createLogger` to the default sinks
+- `src/tagged.ts`:
+   `tagged()` wrapper for composable prefixes
+- `src/sink/console.ts`:
+   `createConsoleSink()`,
+   verbose-mode gating and microtask batching
+- `src/sink/console-control-chars.ts`:
+   control-character neutralization for console-bound text
+- `src/sink/file.ts`:
+   `createFileSink()`,
+   Node.
+  js file sink (JSONL via `appendFile`)
+- `src/sink/indexed-db.ts`:
+   `createIndexedDbSink()`,
+   default persistent-browser sink (one transaction per batch,
+   retention trim)
+- `src/sink/indexed-db-util.ts`:
+   promise bridges for the event-based IndexedDB API
+- `src/sink/opfs.ts`:
+   `createOpfsSink()`,
+   opt-in browser OPFS sink with persistent writable stream (batched writes)
+- `src/sink/record-buffer.ts`:
+   buffering stage shared by the OPFS and sessionStorage sinks
+   (byte cap,
+   severity flush,
+   quiet-period deadline,
+   page lifecycle)
+- `src/sink/session-storage.ts`:
+   `createSessionStorageSink()`,
+   cross-runtime web storage sink (buffering,
+   flush triggers)
+- `src/sink/session-storage-store.ts`:
+   persistence engine behind it (key allocation,
+   footprint accounting,
+   quota eviction)
+- `src/sink/local-storage.ts`:
+   `createLocalStorageSink()`,
+   cross-runtime persistent web storage sink (same buffering,
+   run-scoped keys)
+- `src/sink/local-storage-store.ts`:
+   persistence engine behind it (run identity,
+   prior-run adoption,
+   cross-run oldest-first eviction)
+- `src/sink/local-storage-key.ts`:
+   run-scoped key building,
+   strict parsing,
+   and eviction ordering
+- `src/sink/local-storage-quota.ts` and `src/sink/session-storage-quota.ts`:
+   fill-probed per-runtime quota tables
+- `src/sink/web-storage-runtime.ts` and `src/sink/web-storage-quota-error.ts`:
+   host-runtime detection and quota-overflow recognition shared by both
+  web storage engines
+- `src/sink/noop.ts`:
+   `createNoopSink()`,
+   discards all records