@monochromatic-dev/module-logger 0.1.0

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

@@ -0,0 +1,673 @@
+import { stat as stat$1 } from "node:fs/promises";
+import { dirname as dirname$1, join as join$1 } from "node:path";
+//#region src/types.d.ts
+/**
+ * Log severity levels ordered from least to most severe.
+ */
+type Level = "debug" | "error" | "fatal" | "info" | "trace" | "warn";
+/**
+ * Structured log record written to sinks.
+ */
+type LogRecord = {
+  readonly level: Level;
+  readonly message: string;
+  readonly timestamp: number;
+};
+/**
+ * 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.
+ */
+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.
+ */
+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}.
+ */
+type Sink = {
+  readonly flush?: SinkFlush;
+  readonly verify: Verify;
+  readonly write: (record: LogRecord) => Promise<void>;
+};
+/**
+ * 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.
+ */
+type Logger = {
+  readonly debug: (message: string) => void;
+  readonly error: (message: string) => void;
+  readonly fatal: (message: string) => void;
+  readonly flush: () => Promise<void>;
+  readonly info: (message: string) => void;
+  readonly trace: (message: string) => void;
+  readonly warn: (message: string) => void;
+};
+//#endregion
+//#region src/create-logger.d.ts
+/**
+ * Default `flush()` deadline in milliseconds. Measured on 2026-09-06: a
+ * default logger flushing 100 records through the console and file sinks
+ * settles in about 2 ms locally, so this leaves three orders of magnitude for
+ * a slow but working backend while still bounding shutdown on a wedged one.
+ * Override per logger through the `flushDeadlineMs` option of
+ * {@link createLogger}.
+ */
+export declare const DEFAULT_FLUSH_DEADLINE_MS = 5e3;
+/**
+ * Builds a multi-sink logger over the supplied sink adapters. All
+ * orchestration (per-sink availability, startup buffering and replay,
+ * in-flight write tracking, and flush) lives here; the exported default
+ * `logger` is just this factory applied to the default sink set, and tests
+ * apply it to fake sinks to exercise the orchestration directly.
+ *
+ * Verification runs eagerly at construction and never blocks callers:
+ * records emitted while an async sink is still verifying buffer internally
+ * and replay to that sink the moment it verifies. A sink whose `verify`
+ * resolves `false` or throws is dropped and receives no records. A rejected
+ * `write` is the sink's own concern and does not disable the backend.
+ *
+ * `flush()` always resolves: one deadline (`flushDeadlineMs`, default
+ * {@link DEFAULT_FLUSH_DEADLINE_MS}) wraps startup verification, the
+ * in-flight write drain, and every sink flush hook together. When it elapses
+ * the logger reports one breadcrumb, abandons the tracked writes from its
+ * view (the sinks expose no cancellation, so the underlying work continues),
+ * and resolves, so a wedged backend cannot hang a shutdown.
+ *
+ * @param sinks - Sink adapters to fan each record out to, in priority order.
+ *
+ * @param flushDeadlineMs - Milliseconds one `flush()` may take before it
+ * resolves anyway; raise it for slow but working backends such as network
+ * filesystems.
+ *
+ * @returns Logger plus its eager `initPromise`; callers need not await
+ * `initPromise` before logging, since startup records replay on verify.
+ *
+ * @example
+ * ```ts
+ * const { logger } = createLogger({ sinks: [createConsoleSink()] });
+ * logger.info('ready');
+ * await logger.flush();
+ * ```
+ *
+ * @example
+ * ```ts
+ * const { logger } = createLogger({
+ *   sinks: [createFileSink()],
+ *   flushDeadlineMs: 30_000,
+ * });
+ * ```
+ */
+export declare function createLogger({ sinks, flushDeadlineMs }: {
+  readonly sinks: readonly Sink[];
+  readonly flushDeadlineMs?: number;
+}): {
+  readonly initPromise: Promise<void>;
+  readonly logger: Logger;
+};
+//#endregion
+//#region src/logger.d.ts
+/**
+ * Eager readiness promise. Consumers do not need to await this before logging;
+ * {@link Logger.flush} awaits it internally, and startup records replay to
+ * async sinks as they become available.
+ */
+export declare const initPromise: Promise<void>;
+/**
+ * Multi-sink logger that writes to all available backends.
+ * Startup records replay to async sinks that verify after the log call.
+ * Log calls throw only when initialization proves no backend is available,
+ * which the console sink prevents in every supported runtime.
+ *
+ * @example
+ * ```ts
+ * import { logger, } from '\@monochromatic-dev/module-logger/logger';
+ *
+ * logger.error('unexpected shutdown',);
+ * await logger.flush();
+ * ```
+ */
+export declare const logger: Logger;
+//#endregion
+//#region src/sink/console.d.ts
+/**
+ * Builds a microtask-batched console sink. The pending buffer, schedule flag,
+ * and memoized verbose detection live in this instance's closure (no
+ * module-global state), so independent loggers and tests stay isolated with
+ * no reset hook. Collapses contiguous same-level runs into single `console.*`
+ * calls, sharply reducing console-panel overhead when an instrumented path
+ * emits many records per sync frame.
+ *
+ * @returns Sink that writes formatted lines to `console.*`, except
+ * process-hosted debug records write to stderr.
+ *
+ * @example
+ * ```ts
+ * const { logger } = createLogger({ sinks: [createConsoleSink()] });
+ * logger.info('server started');
+ * ```
+ */
+declare function createConsoleSink(): Sink;
+//#endregion
+//#region src/error-format.d.ts
+/**
+ * Reports a logger-internal caught value without going back through logger
+ * sinks, formatting it via {@link caughtValueText}.
+ *
+ * @param context - Human-readable operation that caught the value.
+ *
+ * @param error - Caught value to include in the diagnostic.
+ *
+ * @mutates error - `caughtValueText` may invoke string-conversion hooks.
+ *
+ * @example
+ * ```ts
+ * reportLoggerInternalError({
+ *   context: 'console sink verify failed',
+ *   error: new Error('blocked'),
+ * });
+ * ```
+ */
+declare function reportLoggerInternalError({ context, error }: {
+  readonly context: string;
+  readonly error: unknown;
+}): void;
+//#endregion
+//#region src/sink/file.d.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
+ * }
+ * ```
+ */
+declare const NO_NODE_MODULES_FOUND: unique symbol;
+/**
+ * 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 });
+ * ```
+ */
+declare function findNodeModulesUp({ cwd, stat, dirname, join, reportError }: {
+  readonly cwd: string;
+  readonly stat: typeof stat$1;
+  readonly dirname: typeof dirname$1;
+  readonly join: typeof join$1;
+  readonly reportError?: typeof reportLoggerInternalError;
+}): Promise<string | typeof NO_NODE_MODULES_FOUND>;
+/**
+ * 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();
+ * ```
+ */
+declare function createFileSink(): Sink;
+//#endregion
+//#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');
+ * ```
+ */
+declare function createIndexedDbSink(): Sink;
+//#endregion
+//#region src/sink/local-storage.d.ts
+/**
+ * Builds a localStorage sink that buffers serialized records through the
+ * shared {@link createRecordBuffer} policy and persists each newline-joined
+ * JSONL batch under a run-scoped counter-incremented key through
+ * {@link createLocalStorageStore}. One uniform write path runs on every
+ * runtime; no per-runtime mode exists. 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}.
+ *
+ * Unlike the sessionStorage sink, whose store dies with the tab, this sink's
+ * batches survive tab close and browser restart, bounded by oldest-first
+ * eviction at half the localStorage quota; that makes it the web storage sink
+ * whose records remain inspectable after a full crash-and-restart.
+ *
+ * @returns Sink backed by web `localStorage`.
+ *
+ * @example
+ * ```ts
+ * const { logger } = createLogger({ sinks: [createLocalStorageSink()] });
+ * logger.info('user signed in'); // buffered
+ * logger.warn('quota near');     // flushes both records in one batch
+ * ```
+ */
+declare function createLocalStorageSink(): Sink;
+//#endregion
+//#region src/sink/noop.d.ts
+/**
+ * Builds a noop sink that discards every record and always verifies as
+ * available. Stateless, so the returned adapters share the same functions;
+ * the factory shape merely matches the other sinks. Useful as a stand-in
+ * that disables logging without removing log calls.
+ *
+ * @returns Sink that discards all records and exposes no `flush` (nothing
+ * is buffered).
+ *
+ * @example
+ * ```ts
+ * const { logger } = createLogger({ sinks: [createNoopSink()] });
+ * logger.info('goes nowhere');
+ * ```
+ */
+declare function createNoopSink(): 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');
+ * ```
+ */
+declare function createOpfsSink(): Sink;
+//#endregion
+//#region src/sink/session-storage.d.ts
+/**
+ * Builds a sessionStorage sink that buffers serialized records through the
+ * shared {@link createRecordBuffer} policy and persists each newline-joined
+ * JSONL batch under a counter-incremented key through
+ * {@link createSessionStorageStore}. One uniform write path runs on every
+ * runtime; no per-runtime mode exists. 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}.
+ *
+ * @returns Sink backed by web `sessionStorage`.
+ *
+ * @example
+ * ```ts
+ * const { logger } = createLogger({ sinks: [createSessionStorageSink()] });
+ * logger.info('user signed in'); // buffered
+ * logger.warn('quota near');     // flushes both records in one batch
+ * ```
+ */
+declare function createSessionStorageSink(): Sink;
+declare namespace index_d_exports {
+  export { NO_NODE_MODULES_FOUND, createConsoleSink, createFileSink, createIndexedDbSink, createLocalStorageSink, createNoopSink, createOpfsSink, createSessionStorageSink, findNodeModulesUp };
+}
+//#endregion
+//#region src/tagged.d.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
+ * ```
+ */
+export declare function tagged({ tag, l }: {
+  readonly l?: Logger;
+  readonly tag: string;
+}): Logger;
+//#endregion
+//#region src/sink/console-control-chars.d.ts
+/**
+ * Neutralizes terminal control characters in console-bound text. One linear
+ * pass over the code points: each neutralized control becomes a `\uXXXX`
+ * escape, everything else is copied through, and newline and tab pass
+ * untouched. Well-formed and malformed escape sequences get no
+ * special treatment because the introducer byte itself is neutralized, so a
+ * trailing lone ESC, an unterminated OSC, and a nested ESC all lose their
+ * teeth the same way.
+ *
+ * @param text - Message text destined for `console.*` or `process.stderr`.
+ *
+ * @returns Text with every neutralized control rendered as `\uXXXX`.
+ *
+ * @example
+ * ```ts
+ * neutralizeControlCharacters('title:\u001B]0;x\u0007 ok\n\tnext');
+ * // => 'title:\\u001B]0;x\\u0007 ok\n\tnext'
+ * ```
+ */
+declare function neutralizeControlCharacters(text: string): string;
+//#endregion
+//#region src/sink/local-storage-key.d.ts
+/**
+ * Parsed identity of one owned localStorage entry, used to order eviction
+ * across runs.
+ */
+type ParsedLogKey = {
+  readonly key: string;
+  readonly stamp: number;
+  readonly nonce: string;
+  readonly index: number;
+};
+/**
+ * Builds the namespaced localStorage key for one batch slot of one run.
+ *
+ * @param stamp - Run creation time ordering runs oldest-first.
+ *
+ * @param nonce - Same-millisecond disambiguator between concurrent tabs.
+ *
+ * @param index - Zero-based batch slot within the run.
+ *
+ * @returns Key such as `monochromatic.log.1753000000000.a1b2.3`.
+ *
+ * @example
+ * ```ts
+ * buildLogKey({ stamp: 1753000000000, nonce: 'a1b2', index: 3 });
+ * ```
+ */
+declare function buildLogKey({ stamp, nonce, index }: {
+  readonly stamp: number;
+  readonly nonce: string;
+  readonly index: number;
+}): string;
+/**
+ * Parses a localStorage key back into its run identity, or reports it foreign
+ * by leaving `parsed` absent. Parsing is strict (exact prefix, exactly the
+ * identity segment count, digit-shaped stamp and index, non-empty nonce)
+ * because eviction trusts this to never classify a host application's key, or
+ * the sessionStorage sink's flat `monochromatic.log.{n}` shape, as evictable.
+ *
+ * @param key - Candidate localStorage key.
+ *
+ * @returns Wrapper whose `parsed` property is present only for an owned key.
+ *
+ * @example
+ * ```ts
+ * parseLogKey('monochromatic.log.1753000000000.a1b2.3').parsed; // ParsedLogKey
+ * parseLogKey('monochromatic.log.5').parsed; // undefined: sessionStorage shape
+ * ```
+ */
+declare function parseLogKey(key: string): {
+  readonly parsed?: ParsedLogKey;
+};
+/**
+ * Orders parsed keys oldest-first for eviction: by run stamp, then by nonce
+ * (an arbitrary but stable tiebreak between same-millisecond runs), then by
+ * batch index within the run.
+ *
+ * @param first - Parsed key compared first.
+ *
+ * @param second - Parsed key compared second.
+ *
+ * @returns Negative when `first` is older, positive when newer, zero on ties.
+ *
+ * @example
+ * ```ts
+ * entries.toSorted(function byOldestFirst(first, second) {
+ *   return compareLogKeys({ first, second });
+ * });
+ * ```
+ */
+declare function compareLogKeys({ first, second }: {
+  readonly first: ParsedLogKey;
+  readonly second: ParsedLogKey;
+}): number;
+//#endregion
+//#region src/sink/local-storage-quota.d.ts
+/**
+ * Detects the current runtime's default localStorage quota in UTF-16 code
+ * units, or `Number.POSITIVE_INFINITY` when the runtime is unrecognized so the
+ * caller leaves its footprint uncapped and relies on reactive eviction alone.
+ *
+ * @returns Total quota in code units, or `Number.POSITIVE_INFINITY` if unknown.
+ *
+ * @example
+ * ```ts
+ * const capChars = detectLocalStorageQuotaChars() / 2; // half the total
+ * ```
+ */
+declare function detectLocalStorageQuotaChars(): number;
+//#endregion
+//#region src/sink/local-storage-store.d.ts
+/**
+ * Builds the persistence engine behind the localStorage sink: each `persist`
+ * lands one already-serialized batch under a run-scoped counter-incremented
+ * key, with proactive and reactive quota eviction. Run identity and counters
+ * live in this instance's closure (no module-global state), so independent
+ * sinks and tests never share keys or need a reset hook.
+ *
+ * Unlike sessionStorage, localStorage is shared by every tab of the origin and
+ * survives restarts, so this engine differs from the sessionStorage engine in
+ * two ways. Keys carry a run identity (see `local-storage-key.ts`), so
+ * concurrent tabs never collide on a counter. And on its first persist the
+ * engine adopts every strictly-parsed entry left by other runs into its
+ * footprint tally, evicting those oldest-first before its own entries;
+ * without that, leftovers from dead sessions would fill the store until no
+ * run could ever write again. Adoption is deferred to first persist rather
+ * than construction so building the default sink set never touches
+ * `globalThis.localStorage` on runtimes where the sink never verifies (plain
+ * Node warns on mere access). Keys that fail the strict parse, including the
+ * host application's, are never counted and never evicted.
+ *
+ * The engine caps its own footprint (adopted entries included) at half the
+ * runtime's localStorage quota, proactively dropping oldest-first, and
+ * reactively drops again if the real store still overflows; see
+ * {@link createLocalStorageStore.persist}.
+ *
+ * @returns Engine exposing `persist` for one batch value per call.
+ *
+ * @example
+ * ```ts
+ * const store = createLocalStorageStore();
+ * store.persist('{"level":"info","message":"hi","timestamp":0}');
+ * ```
+ */
+declare function createLocalStorageStore(): {
+  readonly persist: (batch: string) => void;
+};
+//#endregion
+//#region src/sink/record-buffer.d.ts
+/**
+ * Builds the buffering stage shared by batch-persisting sinks: serialized
+ * records accumulate and leave as one newline-joined JSONL batch through
+ * `onFlush`. One uniform policy runs on every runtime; no per-runtime mode
+ * exists.
+ *
+ * A batch flushes synchronously from inside `add` when it reaches
+ * {@link FLUSH_BUFFER_CAP_CHARS} or when the record's severity is `warn` or
+ * worse, by timer after {@link FLUSH_DEADLINE_MS} of quiet, on `pagehide`
+ * and on the document becoming hidden (where those events exist), and on
+ * `drain`. The byte-cap and severity flushes run on the caller's stack, so
+ * neither a synchronous workload nor a wedged main thread can accumulate
+ * more than one cap of unhanded records. When an addition would breach the
+ * cap, the existing entries flush first so an oversized record's downstream
+ * failure can only ever drop that record, never its batch-mates.
+ *
+ * @param onFlush - Backend handoff receiving each newline-joined batch;
+ * called synchronously from whichever trigger fires, in record order.
+ *
+ * @returns Buffer exposing `add` for records and `drain` for forced flushes.
+ *
+ * @example
+ * ```ts
+ * const buffer = createRecordBuffer({ onFlush: (batch) => store.persist(batch) });
+ * buffer.add({ level: 'info', serialized: JSON.stringify(record) });
+ * buffer.drain();
+ * ```
+ */
+declare function createRecordBuffer({ onFlush }: {
+  readonly onFlush: (batch: string) => void;
+}): {
+  readonly add: (entry: {
+    readonly level: Level;
+    readonly serialized: string;
+  }) => void;
+  readonly drain: () => void;
+};
+//#endregion
+//#region src/sink/session-storage-quota.d.ts
+/**
+ * Detects the current runtime's default sessionStorage quota in UTF-16 code
+ * units, or `Number.POSITIVE_INFINITY` when the runtime is unrecognized so the
+ * caller leaves its footprint uncapped and relies on reactive eviction alone.
+ *
+ * @returns Total quota in code units, or `Number.POSITIVE_INFINITY` if unknown.
+ *
+ * @example
+ * ```ts
+ * const capChars = detectSessionStorageQuotaChars() / 2; // half the total
+ * ```
+ */
+declare function detectSessionStorageQuotaChars(): number;
+//#endregion
+//#region src/sink/web-storage-quota-error.d.ts
+/**
+ * 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(); }
+ * ```
+ */
+declare function isQuotaExceededError(error: unknown): boolean;
+//#endregion
+export { type Level, type LogRecord, type Logger, type Sink, type SinkFlush, type Verify, buildLogKey as _buildLogKey, compareLogKeys as _compareLogKeys, createLocalStorageStore as _createLocalStorageStore, createRecordBuffer as _createRecordBuffer, detectLocalStorageQuotaChars as _detectLocalStorageQuotaChars, detectSessionStorageQuotaChars as _detectSessionStorageQuotaChars, isQuotaExceededError as _isQuotaExceededError, neutralizeControlCharacters as _neutralizeControlCharacters, parseLogKey as _parseLogKey, index_d_exports as sinks };