@monochromatic-dev/module-logger 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @monochromatic-dev/module-logger
 
+## 0.4.0
+
+### Minor Changes
+
+- The default logger is built by the first log or flush call instead of at import,
+   the default sink list is created at that moment,
+   and the package declares `sideEffects: false`.
+  Importing the root entry or `tagged` now runs no sink discovery,
+   no timers,
+   and no I/O,
+   so global-scope-restricted runtimes such as Cloudflare Workers start without the four sink-verification warnings.
+  The `initPromise` root export is removed;
+   `flush()` awaits readiness internally,
+   and `createLogger` still returns its instance's `initPromise`.
+  Commit `7d52ddd`.
+
+## 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

package/README.md

@@ -1,11 +1,13 @@
 # module-logger
 
 Zero-config multi-sink logger with tagged composition.
-Works immediately at import:
- auto-discovers available backends for the current runtime,
+Works immediately with no setup call:
+ the first log or flush call builds the default logger and 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.
+Importing the package runs no discovery,
+ no timers,
+ and no I/O.
 
 ## Usage
 
@@ -56,10 +58,32 @@ Node 24 or newer (the build calls `Error.isError`),
  plus current browsers,
  Deno,
  and Bun for the sinks whose `verify` finds a backend there.
+### Global-scope-restricted runtimes
+
+Cloudflare Workers (and any runtime that forbids timers,
+ I/O,
+ and random values in global scope) can import the root entry and `tagged` freely:
+nothing is built at import,
+ so no sink probe and no timer runs in global scope.
+The first log or flush call inside a handler builds the default logger and verifies its sinks there.
+A Worker that wants a logger scoped to one request can still build its own with `createLogger` over `sinks.createConsoleSink()`
+and hand `flush()` to `ctx.waitUntil`.
+
 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,
@@ -188,15 +212,16 @@ That startup buffer holds at most `STARTUP_BUFFER_CAP` records (10000,
    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,
@@ -250,8 +275,10 @@ File,
 
 ## Error handling
 
-- `initPromise` resolves after eager verification and startup replay;
-   consumers do not await it before logging
+- The default logger is built by the first log or flush call,
+   never at import;
+   there is no readiness promise to await,
+   because `flush()` awaits verification and startup replay internally
 - `logger.flush()` awaits startup verification,
    pending sink writes,
    and sink-owned flush hooks,
@@ -297,10 +324,11 @@ 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,
 },);
@@ -351,6 +379,7 @@ See [DECISIONS.md](DECISIONS.md) for rationale on:
 - `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)
 
@@ -369,6 +398,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};