react-native-nitro-logger 0.1.0

package/lib/typescript/src/destinations/Batcher.d.ts

@@ -0,0 +1,244 @@
+import type { AppendResult, FlushOutcome, SinkStatus } from '../specs/FileSink.nitro.js';
+/**
+ * The part of a `FileSink` the batcher drives. Narrow on purpose: it is what
+ * lets the whole backpressure and loss protocol be tested against a scripted
+ * double, with no native runtime and no filesystem.
+ */
+export interface BatchTarget {
+    appendBatch(batch: string, entryCount: number): AppendResult;
+    getStatus(): SinkStatus;
+    flush(deadlineMs: number): FlushOutcome;
+}
+/** Entries that never reached the file, and the bytes they would have been. */
+export interface LossCounts {
+    readonly entries: number;
+    readonly bytes: number;
+}
+/** Why the sink cut this handle off. Both are terminal for the batcher. */
+export type FenceReason = 'staleGeneration' | 'closed';
+export interface BatcherOptions {
+    /**
+     * Render the consolidated loss notice in the destination's format. The
+     * notice is a record in the log file, so only the destination knows how to
+     * spell it.
+     *
+     * Returning `undefined` (or throwing) leaves the loss unacknowledged rather
+     * than silently forgotten — it will be offered again on the next batch.
+     */
+    readonly renderNotice: (lost: LossCounts) => string | undefined;
+    /**
+     * Called once when the sink fences this handle. The batcher has already
+     * discarded its buffer and baselined its counters by then; the owner
+     * decides between rebinding and self-disabling.
+     */
+    readonly onFenced?: (reason: FenceReason) => void;
+    /** Bytes of pending content that trigger a batch. Default 4096. */
+    readonly batchBytes?: number;
+    /** Idle flush interval, also the backpressure poll interval. Default 100. */
+    readonly flushIntervalMs?: number;
+    /** Pending-buffer caps; whichever binds first. Default 1000 / 512 KB. */
+    readonly maxPendingEntries?: number;
+    readonly maxPendingBytes?: number;
+    /** Sink queue depth at which pushing pauses. Default 256 KB. */
+    readonly watermarkBytes?: number;
+    /** Largest single batch. Default 256 KB. */
+    readonly maxBatchBytes?: number;
+}
+/**
+ * What a bounded drain achieved.
+ *
+ * Deliberately not the sink's `FlushOutcome`: the sink reports monotonic
+ * per-handle totals, whereas `unreportedEntries` / `unreportedBytes` are the
+ * losses that still have no notice in the file. That is the number a caller
+ * can act on, and conflating the two is how "we already logged that" turns
+ * into a loss no one ever hears about.
+ */
+export interface BatchFlushOutcome {
+    /** Every accepted byte reached storage, nothing is buffered, no loss is owed. */
+    readonly durable: boolean;
+    readonly timedOut: boolean;
+    /** Bytes not yet durable: still in the JS buffer plus still in the sink. */
+    readonly pendingBytes: number;
+    readonly unreportedEntries: number;
+    readonly unreportedBytes: number;
+    /** Sink degradation bitmask, passed through. */
+    readonly degraded: number;
+}
+/**
+ * Buffers formatted records and feeds them to a sink under backpressure.
+ *
+ * Three things happen here that do not happen anywhere else.
+ *
+ * **Backpressure.** The sink's queue is bounded, so once it passes the
+ * watermark the batcher stops pushing and polls `getStatus()` instead — which
+ * is why that call is specified never to wait behind writer I/O. Records
+ * accumulate in the JS buffer meanwhile, itself bounded by an entry count and
+ * a byte count.
+ *
+ * **Drop-newest.** When the JS buffer is full the arriving record is dropped,
+ * not the oldest one held. Under a sustained overload the two policies lose
+ * the same volume; they differ in what survives, and the older records are
+ * the ones with the context explaining how the overload started.
+ *
+ * **Loss is owed until it is written.** Every drop — here or in the sink —
+ * accrues to a counter that is only cleared once a notice describing it has
+ * been accepted, and is re-armed if the flush that should have made that
+ * notice durable says otherwise. A loss can therefore be reported twice; it
+ * cannot be reported zero times. Silence has to mean nothing was lost, or the
+ * counters are decoration.
+ */
+export declare class Batcher {
+    private readonly target;
+    private readonly renderNotice;
+    private readonly onFenced;
+    private readonly batchBytes;
+    private readonly flushIntervalMs;
+    private readonly maxPendingEntries;
+    private readonly maxPendingBytes;
+    private readonly watermarkBytes;
+    private readonly maxBatchBytes;
+    private pending;
+    private pendingBytes;
+    private paused;
+    private fenced;
+    private disposed;
+    /**
+     * A notice could not be delivered on its own — unrenderable, or refused by
+     * the sink — and nothing about ticking again would change that.
+     *
+     * The debt stays owed and still shows in `unreported()`; what stops is the
+     * retrying on a timer, which would go on for the life of the process
+     * achieving nothing. The next record to arrive reopens it — that retry
+     * rides a batch that carries the record, so it cannot spin — as does an
+     * explicit `flush()`.
+     */
+    private noticeBlocked;
+    private timer;
+    /** Highest sink totals seen, and every byte this side has dropped. */
+    private observed;
+    /** Covered by a notice the sink has accepted. */
+    private acked;
+    /** Covered by a notice a durable flush has confirmed. */
+    private confirmed;
+    private degraded;
+    constructor(target: BatchTarget, options: BatcherOptions);
+    /**
+     * Buffer one formatted record. Never performs I/O beyond handing a full
+     * batch to the sink, and never throws: a logging call must not fail the
+     * code that made it.
+     */
+    add(record: string): void;
+    /**
+     * Record a loss that happened before the batcher saw it — a record that
+     * could not be rendered, or one too large to be rendered honestly. It is
+     * owed a notice on exactly the same terms as anything dropped here.
+     */
+    noteLoss(entries: number, bytes: number): void;
+    /** Losses with no notice in the file yet. */
+    unreported(): LossCounts;
+    /** Bytes buffered on this side, not yet handed to the sink. */
+    bufferedBytes(): number;
+    /**
+     * Payload-free bitmask of what has stopped working underneath — rotation,
+     * gzip, prune, sidecar, protection.
+     *
+     * This mirrors the sink's own mask, which accumulates bits and drops them
+     * only when a durable purge baselines everything. That is deliberate: these
+     * are things an app wants to know happened *at all*, and a mask that cleared
+     * itself the moment the next batch succeeded would report nothing the one
+     * time it mattered.
+     */
+    degradation(): number;
+    isFenced(): boolean;
+    /**
+     * Drain to the sink and fsync, bounded by a wall-clock deadline.
+     *
+     * Backpressure is overridden for the duration: the whole point of a flush
+     * is to push through a full queue rather than wait for it to clear, so a
+     * rejected batch is followed by a bounded sink flush and retried.
+     *
+     * The postcondition is honest rather than absolute. Under a disk that stays
+     * full, this returns `durable: false` with the losses preserved — the
+     * alternative, insisting everything is either durable or noticed, is a
+     * promise no implementation can keep.
+     */
+    flush(deadlineMs: number): BatchFlushOutcome;
+    /**
+     * Release timers and let the buffer go. Idempotent.
+     *
+     * Deliberately does not flush: `LogDestination` calls `flush()` before
+     * `dispose()`, and a dispose that quietly blocked on a stalled disk would
+     * turn tearing down a destination into a hang.
+     */
+    dispose(): void;
+    /**
+     * Forget everything buffered and start the loss counters over, returning
+     * what was discarded.
+     *
+     * This is the purge path. The counts go back to the caller instead of into
+     * a notice, because a "4,182 entries dropped" line written into a file that
+     * was just cleared for compliance reasons describes the clearing, and the
+     * caller already knows it cleared the file.
+     */
+    discard(): LossCounts;
+    /**
+     * Resume against a fresh generation after the owner has rebound.
+     *
+     * The sink cursors are re-read from scratch rather than carried over,
+     * because the old totals are not a baseline for the new handle's. Whether
+     * the sink resets its per-handle counters on rebind or keeps them running
+     * is not something this side can know — and getting it wrong is silent in
+     * the worse direction: keeping a stale maximum would swallow every new loss
+     * smaller than the pre-purge total, reporting it zero times.
+     *
+     * Local counters are deliberately left alone. Records this side dropped
+     * after the fence went up are real drops of real entries, and they belong
+     * to the new file as much as to the old one.
+     */
+    rebind(): void;
+    /**
+     * Hand at most one batch to the sink.
+     *
+     * The loss snapshot is taken BEFORE the call and acknowledged to that
+     * snapshot rather than to the totals the call returns. A drop that happens
+     * during this very append is not described by the notice riding in it, and
+     * acknowledging the post-call totals would bury it.
+     */
+    private pushOnce;
+    /**
+     * Remove the batch's records from the head of the buffer, optionally
+     * counting them as lost.
+     */
+    private loseHead;
+    private dropped;
+    private fence;
+    /**
+     * Bring the sink's counters up to date without writing anything.
+     *
+     * Cursors normally advance off append results, which means a loss the sink
+     * has recorded but not yet had occasion to report is invisible here. Before
+     * drawing a line under the past — a purge, a fence — that window has to be
+     * closed, or a loss from the old file crosses over and gets described as if
+     * it had happened to the new one.
+     */
+    private syncCounters;
+    /** Declare every loss seen so far as settled, reporting none of it. */
+    private baseline;
+    private noticeText;
+    private delta;
+    private owesNotice;
+    /** Where the drain has got to: records still buffered, loss still owed. */
+    private position;
+    /**
+     * Fold sink counters in. They are monotonic per handle, so the maximum
+     * seen is the truth; a sink that reported a smaller number than last time
+     * would otherwise drive the delta negative and cancel a real loss.
+     */
+    private observeCounts;
+    private targetFlush;
+    private outcome;
+    private ensureTimer;
+    private cancelTimer;
+    private onTick;
+}
+//# sourceMappingURL=Batcher.d.ts.map

package/lib/typescript/src/destinations/Batcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Batcher.d.ts","sourceRoot":"","sources":["../../../../src/destinations/Batcher.ts"],"names":[],"mappings":"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"}

package/lib/typescript/src/destinations/ConsoleDestination.d.ts

@@ -0,0 +1,27 @@
+import type { LogEntry, LogLevel } from '../types.js';
+import type { LogDestination } from './types.js';
+import type { LogFormatter } from '../formatters/types.js';
+/**
+ * Renders to the JS console (Metro in dev). warning → console.warn and
+ * error/todo → console.error deliberately: LogBox surfacing errors in dev is
+ * a feature, not noise.
+ *
+ * `outputSink` mirrors SwiftLogger's test hook: when set, lines are also
+ * handed to the sink, and `isEnabled` stays true even with printing off.
+ */
+export declare class ConsoleDestination implements LogDestination {
+    readonly label = "console";
+    readonly minimumLevel?: LogLevel;
+    printEnabled: boolean;
+    outputSink?: (line: string) => void;
+    private readonly formatter;
+    constructor(options?: {
+        minimumLevel?: LogLevel;
+        formatter?: LogFormatter;
+    });
+    get isEnabled(): boolean;
+    write(entry: LogEntry): void;
+    flush(): void;
+    dispose(): void;
+}
+//# sourceMappingURL=ConsoleDestination.d.ts.map

package/lib/typescript/src/destinations/ConsoleDestination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConsoleDestination.d.ts","sourceRoot":"","sources":["../../../../src/destinations/ConsoleDestination.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAU,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAS,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAqB,CAAC;AAIxD;;;;;;;GAOG;AACH,qBAAa,kBAAmB,YAAW,cAAc;IACvD,QAAQ,CAAC,KAAK,aAAa;IAC3B,QAAQ,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC;IACjC,YAAY,UAAQ;IACpB,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAEpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,OAAO,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,QAAQ,CAAC;QAAC,SAAS,CAAC,EAAE,YAAY,CAAA;KAAE;IAK3E,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,KAAK,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAqB5B,KAAK,IAAI,IAAI;IAIb,OAAO,IAAI,IAAI;CAGhB"}

package/lib/typescript/src/destinations/FileDestination.d.ts

@@ -0,0 +1,200 @@
+import type { LogEntry, LogLevel } from '../types.js';
+import type { LogDestination } from './types.js';
+import type { LogFormatter } from '../formatters/types.js';
+import type { AppendResult, ClearOutcome, FlushOutcome, RotationConfig, SinkStatus } from '../specs/FileSink.nitro.js';
+import type { BatchFlushOutcome, LossCounts } from './Batcher.js';
+/**
+ * The part of `FileSink` a `FileDestination` uses.
+ *
+ * Structural rather than the Nitro interface itself, so the destination can
+ * be driven by a scripted double in tests. The real `FileSink` satisfies it.
+ */
+export interface FileSinkLike {
+    readonly defaultLogDirectory: string;
+    open(path: string, rotation?: RotationConfig, lineFramed?: boolean): void;
+    appendBatch(batch: string, entryCount: number): AppendResult;
+    getStatus(): SinkStatus;
+    flush(deadlineMs: number): FlushOutcome;
+    close(deadlineMs: number): FlushOutcome;
+    getLogFilePaths(): string[];
+    /**
+     * Delete every artifact and bump the writer generation, fencing every
+     * handle on it.
+     *
+     * On `durable && rebound` the CALLING handle is rebound to the new
+     * generation by this call — no second `open` follows, and none would be
+     * accepted, since re-opening a live writer is a config conflict. That is why
+     * the JS side only lifts its own fence afterwards. A `clearLogs` that bumped
+     * the generation without rebinding its caller would leave the destination
+     * writing into a stale handle, discarding every record it was handed and
+     * disabling itself on the first rejection.
+     *
+     * The two flags are separate because they are separate facts. `durable`
+     * answers the compliance question — the artifacts are gone — and a purge can
+     * answer it truthfully and still fail to reopen, on a directory that has
+     * become unwritable or a volume that filled. Only the second flag says there
+     * is somewhere to write.
+     *
+     * On anything else the caller stays fenced along with everyone else, so a
+     * deletion still in flight can never race a fresh write.
+     */
+    clearLogs(deadlineMs: number): ClearOutcome;
+}
+export interface FileDestinationOptions {
+    /** Registration key. Default 'file'. */
+    readonly label?: string;
+    readonly minimumLevel?: LogLevel;
+    /** Default `JsonLinesFormatter` — the one with a framing guarantee. */
+    readonly formatter?: LogFormatter;
+    /** Absolute path. Default `<defaultLogDirectory>/app.log`. */
+    readonly path?: string;
+    readonly rotation?: RotationConfig;
+    /**
+     * Largest single rendered record, in UTF-8 bytes. Default 64 KB — roomy for
+     * a stack trace, far under the sink's payload cap so a batch always fits.
+     */
+    readonly maxEntryBytes?: number;
+    readonly batchBytes?: number;
+    readonly flushIntervalMs?: number;
+    readonly maxPendingEntries?: number;
+    readonly maxPendingBytes?: number;
+    readonly watermarkBytes?: number;
+}
+export interface PurgeOutcome {
+    /** Every artifact is gone. False on any survivor or a blown deadline. */
+    readonly durable: boolean;
+    /**
+     * The destination is writable again, and writing has resumed.
+     *
+     * False means the deletion may well have succeeded — check `durable` — but
+     * the sink did not come back with a usable file, or did not say so. Either
+     * way this destination stays disabled until a retry.
+     */
+    readonly rebound: boolean;
+    readonly deletedCount: number;
+    readonly failedPaths: readonly string[];
+    /** Buffered records thrown away, plus losses that will now go unreported. */
+    readonly discardedEntries: number;
+    readonly discardedBytes: number;
+}
+/**
+ * Writes formatted records to a native file sink, batched and backpressured.
+ *
+ * The division of labour is the whole design: this side decides what to write
+ * and what to give up on, the sink only appends text and reports counters.
+ * Everything interesting — batching, drop policy, loss notices, the purge
+ * handshake — is therefore testable without a device.
+ *
+ * Three behaviours are worth knowing about before using it.
+ *
+ * **Oversized entries are never sliced.** A formatter that can shed structure
+ * is asked to re-render within the limit; one that cannot has its output
+ * replaced whole by a fixed notice. Cutting a rendered record to length is
+ * how a log file stops being parseable, and an unparseable file is worth less
+ * than an honestly incomplete one.
+ *
+ * **Framing is declared, not assumed.** A formatter guaranteeing one record
+ * per line lets the native side trim a torn trailing record after a crash.
+ * Without that guarantee the file is left as the crash left it, because a
+ * writer cannot tell a torn record from an intentional newline.
+ *
+ * **A fenced handle stays fenced.** When the sink reports that this handle's
+ * generation is stale — someone purged the file underneath it — the buffer is
+ * discarded rather than replayed into the new file, and the destination
+ * disables itself. Pre-purge records must not reappear after a compliance
+ * deletion. The handle that invoked the purge rebinds; any other one does
+ * not, and reacquisition is the native registry's job.
+ */
+export declare class FileDestination implements LogDestination {
+    readonly label: string;
+    readonly minimumLevel: LogLevel | undefined;
+    private readonly sink;
+    private readonly formatter;
+    private readonly batcher;
+    private readonly maxEntryBytes;
+    private readonly path;
+    /** Held for the M5 registry's reacquisition path, which needs the same
+     * config the handle was opened with. */
+    private readonly rotation;
+    private fenced;
+    private disposed;
+    constructor(sink: FileSinkLike, options?: FileDestinationOptions);
+    /** True only while this handle may write. */
+    get isEnabled(): boolean;
+    /** Where records are going. */
+    get filePath(): string;
+    /**
+     * Whether the native side may trim a torn trailing record after a crash.
+     * Follows the formatter's declaration; nothing infers it.
+     */
+    get lineFramed(): boolean;
+    write(entry: LogEntry): void;
+    /**
+     * Drain to disk and fsync, bounded by a wall-clock deadline.
+     *
+     * Returns the outcome even though `LogDestination` asks only for `void`: a
+     * caller flushing before backgrounding or on a crash path needs to know
+     * whether it worked, and `durable: false` is the answer that matters.
+     */
+    flush(deadlineMs?: number): BatchFlushOutcome;
+    /** Current file and archives, newest first; empty if the sink refuses. */
+    getLogFilePaths(): string[];
+    /** Losses with no notice in the file yet. */
+    unreportedLoss(): LossCounts;
+    /**
+     * What has stopped working underneath, as a payload-free bitmask —
+     * rotation, gzip, prune, sidecar, protection.
+     *
+     * The mask exists because the alternative is a message, and a message built
+     * from an `errno` string or a path is exactly the kind of thing that carries
+     * a username into a log file. Bits carry no payload, so an app can surface
+     * "log rotation is failing" to support without surfacing anything else.
+     *
+     * Non-zero does not mean records are being lost — a failed compression or a
+     * failed prune costs disk, not data. Check {@link unreportedLoss} for that.
+     */
+    degradation(): number;
+    /**
+     * Delete every log artifact, then rebind.
+     *
+     * The ordering is the point. This handle is fenced first, so nothing can be
+     * written into the window where deletion is in flight; the JS buffer is
+     * discarded rather than flushed, because flushing it would write pre-purge
+     * records into the file a moment before deleting it — or worse, a moment
+     * after. Only a durable deletion lifts the fence. A partial or timed-out
+     * one leaves this handle disabled until an explicit retry, so a late
+     * deletion can never race a fresh write.
+     *
+     * Discarded counts come back here rather than going into a loss notice: a
+     * "4,182 entries dropped" line at the top of a file that was just cleared
+     * for compliance describes the clearing, which the caller already knows
+     * about.
+     */
+    purge(deadlineMs?: number): PurgeOutcome;
+    /** Idempotent: flush what is buffered, release the timer, close the sink. */
+    dispose(): void;
+    /**
+     * Render one entry, or account for why it could not be rendered.
+     *
+     * Returns undefined when nothing writable came out; the loss is recorded
+     * before returning, so an entry is either in the file or in the counters
+     * and never in neither.
+     */
+    private renderRecord;
+    private renderLossNotice;
+    /**
+     * Render one of the pipeline's own notices under the same per-entry limit
+     * as everything else.
+     *
+     * The limit exists so a batch always fits the sink. A notice exempt from it
+     * could be refused forever by a sink that will never take it, and the loss
+     * it describes would sit undelivered behind it — the pipeline's own
+     * diagnostics jamming the pipeline. Returning undefined when nothing fits
+     * leaves the loss counted and owed, which is the honest outcome.
+     */
+    private boundedNotice;
+    private formatOrUndefined;
+    private formatWithinOrUndefined;
+    private onFenced;
+}
+//# sourceMappingURL=FileDestination.d.ts.map

package/lib/typescript/src/destinations/FileDestination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileDestination.d.ts","sourceRoot":"","sources":["../../../../src/destinations/FileDestination.ts"],"names":[],"mappings":"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"}

package/lib/typescript/src/destinations/NativeConsoleDestination.d.ts

@@ -0,0 +1,86 @@
+import type { LogEntry, LogLevel } from '../types.js';
+import type { LogDestination } from './types.js';
+import type { LogFormatter } from '../formatters/types.js';
+/**
+ * The part of `NativeConsoleSink` this destination uses.
+ *
+ * Structural rather than the Nitro interface itself, so tests can drive it
+ * with a double. The real `NativeConsoleSink` satisfies it.
+ */
+export interface NativeConsoleSinkLike {
+    install(subsystem: string, category: string): void;
+    logBatch(levels: number[], messages: string[]): void;
+}
+export interface NativeConsoleDestinationOptions {
+    /** Registration key. Default 'native-console'. */
+    readonly label?: string;
+    readonly minimumLevel?: LogLevel;
+    /** Default `DefaultFormatter` — os_log wants a line, not a JSON record. */
+    readonly formatter?: LogFormatter;
+    /** Reverse-DNS, as os_log expects. Default: the bundle's, chosen natively. */
+    readonly subsystem?: string;
+    /** Default 'log'. Becomes the logcat tag on Android. */
+    readonly category?: string;
+    /** Entries per bridge crossing. Default 64. */
+    readonly batchSize?: number;
+    /** Idle coalescing window. Default 100 ms. */
+    readonly flushIntervalMs?: number;
+    /** Buffer ceiling; oldest survive, newest are dropped. Default 1000. */
+    readonly maxPendingEntries?: number;
+}
+/**
+ * Renders entries into the platform log stream — os_log on iOS, logcat on
+ * Android — so JS logs interleave with native ones in Console.app and Xcode.
+ *
+ * Batched, unlike {@link ConsoleDestination}: one bridge crossing per drain
+ * with two parallel primitive arrays, rather than a crossing per entry.
+ *
+ * Deliberately simpler than {@link FileDestination}. There is no backpressure
+ * and no loss accounting because there is nothing to push back on: os_log
+ * accepts what it is given and never blocks on a disk. What this destination
+ * does account for is its own buffer — entries dropped at the ceiling, and
+ * entries lost to a throwing sink — through {@link dropped}, because a
+ * diagnostic channel that quietly loses records is worse than one that says
+ * it did.
+ *
+ * The durable copy is the file destination's. Nothing here is a system of
+ * record, which is what makes best-effort the right posture.
+ */
+export declare class NativeConsoleDestination implements LogDestination {
+    readonly label: string;
+    readonly minimumLevel?: LogLevel;
+    private readonly sink;
+    private readonly formatter;
+    private readonly batchSize;
+    private readonly flushIntervalMs;
+    private readonly maxPending;
+    private levels;
+    private messages;
+    private timer;
+    private disposed;
+    private failures;
+    private droppedEntries;
+    constructor(sink: NativeConsoleSinkLike, options?: NativeConsoleDestinationOptions);
+    /**
+     * False once disposed, or once the native sink has failed enough times in a
+     * row to be considered gone. The Logger checks this before formatting, so a
+     * dead sink stops costing render work as well as bridge calls.
+     */
+    get isEnabled(): boolean;
+    /** Entries this destination never handed to the platform log. */
+    dropped(): number;
+    write(entry: LogEntry): void;
+    /**
+     * Hands everything buffered to the platform log.
+     *
+     * The deadline is accepted and ignored, deliberately: `logBatch` does not
+     * wait on anything, so there is no wait to bound. Taking the parameter keeps
+     * the destination interchangeable with the ones that do need it.
+     */
+    flush(_deadlineMs?: number): void;
+    dispose(): void;
+    private drain;
+    private arm;
+    private cancel;
+}
+//# sourceMappingURL=NativeConsoleDestination.d.ts.map

package/lib/typescript/src/destinations/NativeConsoleDestination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NativeConsoleDestination.d.ts","sourceRoot":"","sources":["../../../../src/destinations/NativeConsoleDestination.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAU,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAS,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAqB,CAAC;AAIxD;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CACtD;AAED,MAAM,WAAW,+BAA+B;IAC9C,kDAAkD;IAClD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC;IACjC,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,CAAC,EAAE,YAAY,CAAC;IAClC,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,8CAA8C;IAC9C,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,wEAAwE;IACxE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAcD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,wBAAyB,YAAW,cAAc;IAC7D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC;IAEjC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAwB;IAC7C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,QAAQ,CAAgB;IAChC,OAAO,CAAC,KAAK,CAA4C;IACzD,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,cAAc,CAAK;gBAGzB,IAAI,EAAE,qBAAqB,EAC3B,OAAO,CAAC,EAAE,+BAA+B;IAkB3C;;;;OAIG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,iEAAiE;IACjE,OAAO,IAAI,MAAM;IAIjB,KAAK,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAuC5B;;;;;;OAMG;IACH,KAAK,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI;IAIjC,OAAO,IAAI,IAAI;IASf,OAAO,CAAC,KAAK;IAwBb,OAAO,CAAC,GAAG;IAQX,OAAO,CAAC,MAAM;CAKf"}

package/lib/typescript/src/destinations/types.d.ts

@@ -0,0 +1,19 @@
+import type { LogEntry, LogLevel } from '../types.js';
+/**
+ * A log output backend. The Logger filters on `isEnabled` and `minimumLevel`
+ * BEFORE evaluating a lazy message, isolates each destination's `write` (one
+ * throwing destination never blocks siblings), and calls `dispose()` on
+ * replace/remove/reset — JS garbage collection is nondeterministic, so
+ * timers, native handles, and listeners must be released explicitly.
+ */
+export interface LogDestination {
+    readonly label: string;
+    readonly minimumLevel?: LogLevel;
+    readonly isEnabled: boolean;
+    write(entry: LogEntry): void;
+    /** Drain any buffered output synchronously (bounded by deadlineMs). */
+    flush(deadlineMs?: number): void;
+    /** Idempotent: cancel timers, flush, release native handles/listeners. */
+    dispose(): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/typescript/src/destinations/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/destinations/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAU,CAAC;AAEnD;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,KAAK,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC7B,uEAAuE;IACvE,KAAK,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,0EAA0E;IAC1E,OAAO,IAAI,IAAI,CAAC;CACjB"}

package/lib/typescript/src/formatters/DefaultFormatter.d.ts

@@ -0,0 +1,22 @@
+import type { LogEntry } from '../types.js';
+import type { LogFormatter } from './types.js';
+/**
+ * SwiftLogger's default layout minus the `File.swift:42` column (no call-site
+ * capture in JS):
+ *
+ *     LEVEL | HH:mm:ss.SSS | [correlation] [subsystem] message {key=value}
+ *
+ * Metadata renders as `key=value` pairs sorted by key.
+ *
+ * A multi-line message keeps its lines, indented under the message column:
+ *
+ *     ERROR | 12:15:30.842 | Unhandled TypeError
+ *           |              | at foo (bundle.js:1:2)
+ *
+ * See {@link CONTINUATION} for why that indent is load-bearing rather than
+ * decorative.
+ */
+export declare class DefaultFormatter implements LogFormatter {
+    format(entry: LogEntry): string;
+}
+//# sourceMappingURL=DefaultFormatter.d.ts.map

package/lib/typescript/src/formatters/DefaultFormatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DefaultFormatter.d.ts","sourceRoot":"","sources":["../../../../src/formatters/DefaultFormatter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAU,CAAC;AACzC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAS,CAAC;AAI5C;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,gBAAiB,YAAW,YAAY;IACnD,MAAM,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM;CAyBhC"}