@monochromatic-dev/module-logger 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @monochromatic-dev/module-logger
 
+## 0.3.0
+
+### Minor Changes
+
+- The root entry is now platform-neutral and neither built artifact contains a dynamic `import()`.
+  `createFileSink` moved to `@monochromatic-dev/module-logger/node`;
+   `createIndexedDbSink` and `createOpfsSink` moved to `@monochromatic-dev/module-logger/browser`.
+  The default logger keeps file logging under the `node` export condition and IndexedDB under `default`;
+   a Node consumer whose bundler resolves `default` no longer gets file logging.
+  Commit `ce38d07`.
+
+## 0.2.0
+
+### Minor Changes
+
+- Records logged before every sink has answered its verify now buffer under `STARTUP_BUFFER_CAP` (10000,
+   exported).
+  On overflow the oldest buffered record is dropped,
+   and once initialization completes one `warn` record naming the dropped count is written to every available sink.
+  Commit `fee2427`.
+- Sinks now verify concurrently,
+   each under a time limit.
+  A backend probe that never answers no longer starves the sinks after it or keeps the logger from initializing.
+  The limit is the new `createLogger` option `verifyTimeoutMs` (default `DEFAULT_VERIFY_TIMEOUT_MS`,
+   5000 ms).
+  Commit `ee58222`.
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -60,6 +60,17 @@ 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`.
 
+The root entry is platform-neutral and is built twice.
+The `node` export condition serves a build whose default logger includes the file sink,
+ with static `node:fs/promises` and `node:path` imports,
+ and which carries no browser storage code.
+Every other resolution (`default`) serves a build whose default logger includes the IndexedDB sink
+ and which references no Node module.
+Neither build contains a dynamic `import()`,
+ and a unit test reads every chunk of both builds to keep it that way.
+The root types are identical on both conditions.
+A Node consumer whose bundler resolves the `default` condition gets the neutral build and no file logging.
+
 ## Log levels
 
 Six levels,
@@ -89,9 +100,19 @@ 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
+Availability is verified at module load,
+ every sink concurrently,
+ each under its own time limit (`verifyTimeoutMs`,
+ default `DEFAULT_VERIFY_TIMEOUT_MS`,
+ 5000 ms);
+ a sink that does not answer in time counts as unavailable,
+ so one hung backend probe cannot starve the others.
+Records emitted while an async sink is
 still being verified are replayed to that sink when it becomes available.
+That startup buffer holds at most `STARTUP_BUFFER_CAP` records (10000,
+ exported);
+ past the cap the oldest buffered record is dropped,
+ and once every sink has answered one `warn` record naming the dropped count is written to every available sink.
 
 - **console**:
    formats as `[level] [ISO timestamp] message`;
@@ -178,15 +199,16 @@ still being verified are replayed to that sink when it becomes available.
    discards all records;
    a stand-in that disables logging without removing log calls
 
-Each sink is a factory,
+Each sink is a factory.
+The cross-platform ones,
  `createConsoleSink()`,
- `createFileSink()`,
- `createIndexedDbSink()`,
- `createOpfsSink()`,
-`createSessionStorageSink()`,
+ `createSessionStorageSink()`,
  `createLocalStorageSink()`,
  and `createNoopSink()`,
- exported under the `sinks` namespace.
+ are exported under the `sinks` namespace of the root entry.
+`createFileSink()` is exported from `@monochromatic-dev/module-logger/node`,
+ and `createIndexedDbSink()` and `createOpfsSink()` from `@monochromatic-dev/module-logger/browser`,
+ so importing a platform-only sink is the consumer's own assertion of the platform.
 A sink instance keeps its own buffers,
  streams,
  and counters,
@@ -256,9 +278,15 @@ File,
 - 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
+- A sink is dropped when its `verify` reports unavailable,
+   runs past `verifyTimeoutMs`,
+   or its flush hook rejects;
+   remaining sinks continue,
+   and a late verify answer after the limit is ignored
 - Individual `write` failures are handled per sink and do not disable the backend
+- Records logged before every sink has answered buffer under `STARTUP_BUFFER_CAP`;
+   on overflow the oldest is dropped and the count is reported as one `warn` record after initialization,
+   never silently
 
 ## Custom loggers
 
@@ -281,11 +309,13 @@ Raise the flush deadline for a slow but working backend,
  such as a network filesystem:
 
 ```ts
-import { createLogger, sinks, } from '@monochromatic-dev/module-logger';
+import { createLogger, } from '@monochromatic-dev/module-logger';
+import { createFileSink, } from '@monochromatic-dev/module-logger/node';
 
 const { logger, } = createLogger({
-  sinks: [sinks.createFileSink(),],
+  sinks: [createFileSink(),],
   flushDeadlineMs: 30_000,
+  verifyTimeoutMs: 30_000,
 },);
 ```
 
@@ -332,6 +362,11 @@ See [DECISIONS.md](DECISIONS.md) for rationale on:
 - localStorage and IndexedDB sink designs and measurements
 - Console output neutralizes control characters
 - `flush()` has a deadline
+- Sinks verify concurrently under a time limit
+- The startup buffer is bounded and overflow is reported
+- Platform-specific sinks live behind `./node` and `./browser`
+- Zero-config at import,
+   no configure step (the logtape migration observations)
 
 ## Source files
 
@@ -348,6 +383,17 @@ See [DECISIONS.md](DECISIONS.md) for rationale on:
    flush)
 - `src/logger.ts`:
    default singleton built by applying `createLogger` to the default sinks
+- `src/node.ts`:
+   the `./node` subpath entry,
+   `createFileSink()`
+- `src/browser.ts`:
+   the `./browser` subpath entry,
+   `createIndexedDbSink()` and `createOpfsSink()`
+- `src/default-sinks.node.ts` and `src/default-sinks.neutral.ts`:
+   the two default sink lists,
+   selected at build time through the `#default-sinks` entry of `package.json` `imports`
+- `src/artifact-platform-split.unit.test.ts`:
+   guard that reads every chunk of both builds and rejects dynamic imports and cross-platform leaks
 - `src/tagged.ts`:
    `tagged()` wrapper for composable prefixes
 - `src/sink/console.ts`:

package/dist/final/neutral/browser.d.mts

@@ -0,0 +1,60 @@
+import { i as Sink } from "./types-BkkBXgY3.mjs";
+//#region src/sink/indexed-db.d.ts
+/**
+Builds an IndexedDB sink that buffers serialized records through the shared
+{@link createRecordBuffer} policy and persists each newline-joined JSONL
+batch as one string value per transaction, measured at 0.15 µs of
+main-thread enqueue per record on headless Chromium 149 (one `add` per
+32 KiB batch). The connection lives in this instance's closure (no
+module-global state), so independent loggers and tests never share a
+handle or need a reset hook.
+
+Records are readable the moment their transaction settles (DevTools
+Application tab included), survive tab close and browser restart, and
+auto-incremented keys serialize across tabs, so no run-scoped naming is
+needed. Retention trims oldest-first past {@link MAX_STORED_BATCHES}.
+Transactions use the default relaxed durability: relaxed commits reach the
+browser's storage backend promptly and survive renderer crashes, and the
+OS-crash window `durability: 'strict'` would close is the rarest failure
+class, not worth an fsync per batch.
+
+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}. The sink's `flush` hook awaits
+every issued batch transaction before resolving.
+
+@returns Sink backed by IndexedDB.
+
+@example
+```ts
+const { logger } = createLogger({ sinks: [createIndexedDbSink()] });
+logger.warn('quota nearing limit');
+```
+*/
+export declare function createIndexedDbSink(): Sink;
+//#endregion
+//#region src/sink/opfs.d.ts
+/**
+Builds an OPFS sink that buffers serialized records through the shared
+{@link createRecordBuffer} policy and appends each newline-joined JSONL
+batch to a per-session file in the Origin Private File System with one
+stream write per batch. The kept-open writable stream lives in this
+instance's closure (no module-global state), so independent loggers and
+tests never share a handle or need a reset hook.
+
+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}. Batch writes queue on the stream
+in issue order, so ordering holds at the batch boundary, and the sink's
+`flush` hook awaits every issued batch before resolving.
+
+@returns Sink backed by OPFS.
+
+@example
+```ts
+const { logger } = createLogger({ sinks: [createOpfsSink()] });
+logger.warn('quota nearing limit');
+```
+*/
+export declare function createOpfsSink(): Sink;
+//#endregion

package/dist/final/neutral/browser.mjs

@@ -0,0 +1 @@
+import{n as createRecordBuffer,r as reportLoggerInternalError,t as createIndexedDbSink}from"./indexed-db-hsIfv7Cv.mjs";function createOpfsSink(){let state={},pendingBatchWrites=new Set;async function verify(){try{let opfsRoot=await navigator.storage.getDirectory(),timestamp=new Date().toISOString().replaceAll(`:`,`-`),fileHandle=await opfsRoot.getFileHandle(`monochromatic-${timestamp}.log.jsonl`,{create:!0}),probeWritable=await fileHandle.createWritable({keepExistingData:!0}),testData=`{"test":true,"timestamp":${Date.now()}}\n`;await probeWritable.write(testData),await probeWritable.close();let available=(await(await fileHandle.getFile()).text()).includes(`"test":true`);return available&&(state.writable=await fileHandle.createWritable({keepExistingData:!0})),available}catch(error){let opfsStorage=globalThis.navigator?.storage;return opfsStorage!==void 0&&`getDirectory`in opfsStorage&&reportLoggerInternalError({context:`OPFS sink verification failed`,error}),!1}}async function writeBatch(batch){if(state.writable)try{await state.writable.write(`${batch}\n`)}catch(error){reportLoggerInternalError({context:`OPFS sink record write failed`,error})}}async function removePendingWhenSettled(pending){await pending,pendingBatchWrites.delete(pending)}function handOffBatch(batch){let pending=writeBatch(batch);pendingBatchWrites.add(pending),removePendingWhenSettled(pending)}let buffer=createRecordBuffer({onFlush:handOffBatch});function write(record){return buffer.add({level:record.level,serialized:JSON.stringify(record)}),Promise.resolve()}async function flush(){buffer.drain();let writes=[...pendingBatchWrites];await Promise.all(writes)}return{flush,verify,write}}export{createIndexedDbSink,createOpfsSink};