react-native-nitro-logger 0.1.0

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

@@ -0,0 +1,73 @@
+import type { LogEntry } from '../types.js';
+import type { LogFormatter } from './types.js';
+import { utf8Length } from '../utf8.js';
+export { utf8Length };
+/**
+ * How the `timestamp` field renders.
+ *
+ * `iso8601` is UTC with milliseconds — `2026-07-27T12:15:30.842Z` — and is
+ * what the SwiftLogger goldens are written against. `epochSeconds` emits a
+ * JSON number of seconds, for aggregators that would only parse the string
+ * back again.
+ */
+export type JsonTimestampStyle = 'iso8601' | 'epochSeconds';
+export interface JsonLinesFormatterOptions {
+    readonly timestampStyle?: JsonTimestampStyle;
+}
+/**
+ * One JSON object per line, matching SwiftLogger's `JSONLogFormatter`.
+ *
+ * Keys come out in a fixed order — `timestamp`, `level`, `message`, then the
+ * optional `correlation`, `subsystem`, and `metadata` — so that output diffs
+ * cleanly and goldens are stable. Absent optionals are omitted rather than
+ * written as null, and metadata values keep their JSON type.
+ *
+ * Metadata keys are sorted, which is also why the object is assembled by hand
+ * rather than handed to `JSON.stringify`. JavaScript orders integer-like
+ * string keys before all others, so `JSON.stringify({ b: 1, '2': 2 })` puts
+ * `2` first no matter what order the keys went in. A metadata key is whatever
+ * the caller wrote, `'2'` included, and the Swift side sorts every key the
+ * same way.
+ *
+ * See `docs/PARITY.md` for the field-by-field comparison, including the three
+ * fields this formatter deliberately does not emit.
+ */
+export declare class JsonLinesFormatter implements LogFormatter {
+    /**
+     * Every control character is escaped, so a record cannot contain a raw
+     * newline and native crash-tail trimming can find record boundaries.
+     */
+    readonly framing: "line";
+    private readonly timestampStyle;
+    constructor(options?: JsonLinesFormatterOptions);
+    format(entry: LogEntry): string;
+    /**
+     * Render within a byte budget, shedding content in a fixed order rather
+     * than slicing the finished string.
+     *
+     * Cutting a JSON record to length produces something no parser will accept,
+     * and a log line that cannot be parsed is worth less than one that is
+     * honestly incomplete. So: drop metadata from the end of sorted key order,
+     * then shorten the message, and mark the result `"truncated":true` either
+     * way. A reader can tell the difference between a short message and a
+     * shortened one.
+     *
+     * The budget counts UTF-8 bytes, because that is what the sink reserves.
+     * An unpaired surrogate never distorts the count here: `JSON.stringify` has
+     * already turned it into a six-character `\udXXX` escape by the time
+     * anything is measured.
+     *
+     * When even an empty message will not fit, the result comes back OVER
+     * budget: it is the smallest record that still identifies the entry, which
+     * is not quite the same as the smallest record possible. `correlation` and
+     * `subsystem` survive, because an entry no one can place is worth less than
+     * a short one — dropping them would save bytes and leave a line that says
+     * nothing about where it came from. Callers deciding whether an entry is
+     * renderable at all must therefore measure the result rather than assume it
+     * fits.
+     */
+    formatWithin(entry: LogEntry, maxBytes: number): string;
+    private render;
+    private renderTimestamp;
+}
+//# sourceMappingURL=JsonLinesFormatter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"JsonLinesFormatter.d.ts","sourceRoot":"","sources":["../../../../src/formatters/JsonLinesFormatter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAkC,MAAM,aAAU,CAAC;AACzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAS,CAAC;AAE5C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAS,CAAC;AAErC,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,cAAc,CAAC;AAE5D,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,cAAc,CAAC,EAAE,kBAAkB,CAAC;CAC9C;AAKD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,kBAAmB,YAAW,YAAY;IACrD;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAG,MAAM,CAAU;IAEnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;gBAExC,OAAO,GAAE,yBAA8B;IAInD,MAAM,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM;IAI/B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,YAAY,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IA0CvD,OAAO,CAAC,MAAM;IAmCd,OAAO,CAAC,eAAe;CAWxB"}

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

@@ -0,0 +1,6 @@
+/** Local-time `HH:mm:ss.SSS`, matching SwiftLogger's console timestamp.
+ * Takes epoch milliseconds (see `LogEntry.timestamp`); plain Date getters +
+ * zero-pad — none of the Swift version's caching is needed, these are cheap
+ * in JS. */
+export declare function formatTime(epochMs: number): string;
+//# sourceMappingURL=timestamp.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"timestamp.d.ts","sourceRoot":"","sources":["../../../../src/formatters/timestamp.ts"],"names":[],"mappings":"AAAA;;;YAGY;AACZ,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAOlD"}

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

@@ -0,0 +1,27 @@
+import type { LogEntry } from '../types.js';
+export interface LogFormatter {
+    /**
+     * Framing contract for file destinations: 'line' guarantees exactly one
+     * escaped record per line (newlines in content are escaped), which is what
+     * makes native crash-tail trimming safe. Formatters that cannot guarantee
+     * this omit it and are documented as having reduced crash-tail recovery.
+     */
+    readonly framing?: 'line';
+    format(entry: LogEntry): string;
+    /**
+     * Render `entry` within a UTF-8 byte budget by shedding content
+     * structurally — dropping whole fields, truncating a field at code-point
+     * boundaries — so the result is still well-formed in this format.
+     *
+     * A formatter that omits this is never sliced to fit: an entry too large
+     * for the destination's per-entry limit is replaced whole by a fixed
+     * notice, because cutting a rendered record to length is how a log file
+     * stops being parseable.
+     *
+     * Best effort. Returning something still over budget is allowed — a record
+     * has a floor below which it no longer identifies anything — and callers
+     * must measure the result rather than assume it fits.
+     */
+    formatWithin?(entry: LogEntry, maxBytes: number): string;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/formatters/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAU,CAAC;AAEzC,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAE1B,MAAM,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAAC;IAEhC;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1D"}

package/lib/typescript/src/index.d.ts

@@ -0,0 +1,34 @@
+import type { FileSink } from './specs/FileSink.nitro.js';
+import type { NativeConsoleSink } from './specs/NativeConsoleSink.nitro.js';
+export { Log, Logger } from './Logger.js';
+export type { LogOptions } from './Logger.js';
+export { ScopedLogger } from './ScopedLogger.js';
+export type { LogLevel, LazyMessage, LogPrimitive, LogValue, LogMetadata, RedactedMetadata, LogEntry, } from './types.js';
+export { pub, priv } from './privacy.js';
+export { METADATA_KEY_PATTERN_SOURCE, DROPPED_COUNT_KEY, MAX_CATALOG_SIZE, UNREADABLE_VALUE, } from './privacy.js';
+export type { PublicValue, PrivateValue, PrivacyDefault } from './privacy.js';
+export type { LogDestination } from './destinations/types.js';
+export { ConsoleDestination } from './destinations/ConsoleDestination.js';
+export { FileDestination } from './destinations/FileDestination.js';
+export type { FileDestinationOptions, FileSinkLike, PurgeOutcome, } from './destinations/FileDestination.js';
+export { NativeConsoleDestination } from './destinations/NativeConsoleDestination.js';
+export type { NativeConsoleDestinationOptions, NativeConsoleSinkLike, } from './destinations/NativeConsoleDestination.js';
+export { installErrorHandler } from './integrations/errorHandler.js';
+export { ERROR_METADATA_KEYS, UNCAUGHT_ERROR_MESSAGE, } from './integrations/errorHandler.js';
+export type { ErrorHandlerOptions, ErrorUtilsLike, Uninstall, } from './integrations/errorHandler.js';
+export { flushOnBackground } from './integrations/appState.js';
+export type { FlushOnBackgroundOptions, AppStateLike, } from './integrations/appState.js';
+export { sanitizeError, DEFAULT_BUNDLE_NAMES, DEFAULT_MAX_FRAMES, REDACTED_FRAME, REDACTED_MESSAGE, UNKNOWN_ERROR_NAME, NON_ERROR_THROWN, } from './integrations/sanitizeError.js';
+export type { SanitizedError, SanitizeErrorOptions, } from './integrations/sanitizeError.js';
+export { Batcher } from './destinations/Batcher.js';
+export type { BatchTarget, BatchFlushOutcome, BatcherOptions, FenceReason, LossCounts, } from './destinations/Batcher.js';
+export { utf8Length } from './utf8.js';
+export type { LogFormatter } from './formatters/types.js';
+export { DefaultFormatter } from './formatters/DefaultFormatter.js';
+export { JsonLinesFormatter } from './formatters/JsonLinesFormatter.js';
+export type { JsonTimestampStyle, JsonLinesFormatterOptions, } from './formatters/JsonLinesFormatter.js';
+export type { FileSink, RotationConfig, RejectReason, SinkStatus, AppendResult, FlushOutcome, ClearOutcome, } from './specs/FileSink.nitro.js';
+export type { NativeConsoleSink } from './specs/NativeConsoleSink.nitro.js';
+export declare function createFileSink(): FileSink;
+export declare function createNativeConsoleSink(): NativeConsoleSink;
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oCAAiC,CAAC;AAGzE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,aAAU,CAAC;AACvC,YAAY,EAAE,UAAU,EAAE,MAAM,aAAU,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAgB,CAAC;AAC9C,YAAY,EACV,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,QAAQ,GACT,MAAM,YAAS,CAAC;AACjB,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,cAAW,CAAC;AACtC,OAAO,EACL,2BAA2B,EAC3B,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,cAAW,CAAC;AACnB,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,cAAW,CAAC;AAC3E,YAAY,EAAE,cAAc,EAAE,MAAM,yBAAsB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sCAAmC,CAAC;AACvE,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAgC,CAAC;AACjE,YAAY,EACV,sBAAsB,EACtB,YAAY,EACZ,YAAY,GACb,MAAM,mCAAgC,CAAC;AACxC,OAAO,EAAE,wBAAwB,EAAE,MAAM,4CAAyC,CAAC;AACnF,YAAY,EACV,+BAA+B,EAC/B,qBAAqB,GACtB,MAAM,4CAAyC,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAA6B,CAAC;AAClE,OAAO,EACL,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,gCAA6B,CAAC;AACrC,YAAY,EACV,mBAAmB,EACnB,cAAc,EACd,SAAS,GACV,MAAM,gCAA6B,CAAC;AACrC,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAAyB,CAAC;AAC5D,YAAY,EACV,wBAAwB,EACxB,YAAY,GACb,MAAM,4BAAyB,CAAC;AACjC,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,iCAA8B,CAAC;AACtC,YAAY,EACV,cAAc,EACd,oBAAoB,GACrB,MAAM,iCAA8B,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,2BAAwB,CAAC;AACjD,YAAY,EACV,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,WAAW,EACX,UAAU,GACX,MAAM,2BAAwB,CAAC;AAChC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAQ,CAAC;AACpC,YAAY,EAAE,YAAY,EAAE,MAAM,uBAAoB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAA+B,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAiC,CAAC;AACrE,YAAY,EACV,kBAAkB,EAClB,yBAAyB,GAC1B,MAAM,oCAAiC,CAAC;AAKzC,YAAY,EACV,QAAQ,EACR,cAAc,EACd,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,YAAY,GACb,MAAM,2BAAwB,CAAC;AAChC,YAAY,EAAE,iBAAiB,EAAE,MAAM,oCAAiC,CAAC;AAEzE,wBAAgB,cAAc,IAAI,QAAQ,CAEzC;AAED,wBAAgB,uBAAuB,IAAI,iBAAiB,CAI3D"}

package/lib/typescript/src/integrations/appState.d.ts

@@ -0,0 +1,33 @@
+import type { Logger } from '../Logger.js';
+import type { Uninstall } from './errorHandler.js';
+/** The part of RN's `AppState` this uses. Injected in tests. */
+export interface AppStateLike {
+    addEventListener(type: 'change', listener: (state: string) => void): {
+        remove(): void;
+    } | undefined;
+}
+export interface FlushOnBackgroundOptions {
+    /** Defaults to the shared `Log`. */
+    readonly logger?: Logger;
+    /** Injected for tests; defaults to `require('react-native').AppState`. */
+    readonly appState?: AppStateLike;
+    /**
+     * Budget for the backgrounding flush. Default 2000 ms.
+     *
+     * Backgrounding is not a crash, but it is the last moment the JS thread is
+     * reliably scheduled: iOS may freeze timers immediately afterwards, and an
+     * entry still sitting in a 100 ms batch window can wait there until the app
+     * is next opened — or be lost if it is killed while suspended.
+     */
+    readonly deadlineMs?: number;
+}
+/**
+ * Flushes every destination when the app leaves the foreground.
+ *
+ * Returns an idempotent uninstall handle. Removing the listener matters more
+ * than it looks: `AppState` outlives any component, so a subscription left
+ * behind keeps a disposed logger reachable and flushes it on every transition
+ * for the rest of the process.
+ */
+export declare function flushOnBackground(options?: FlushOnBackgroundOptions): Uninstall;
+//# sourceMappingURL=appState.d.ts.map

package/lib/typescript/src/integrations/appState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appState.d.ts","sourceRoot":"","sources":["../../../../src/integrations/appState.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAW,CAAC;AAExC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAgB,CAAC;AAEhD,gEAAgE;AAChE,MAAM,WAAW,YAAY;IAC3B,gBAAgB,CACd,IAAI,EAAE,QAAQ,EACd,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAChC;QAAE,MAAM,IAAI,IAAI,CAAA;KAAE,GAAG,SAAS,CAAC;CACnC;AAED,MAAM,WAAW,wBAAwB;IACvC,oCAAoC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;IACjC;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAiBD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,CAAC,EAAE,wBAAwB,GACjC,SAAS,CAgCX"}

package/lib/typescript/src/integrations/errorHandler.d.ts

@@ -0,0 +1,55 @@
+import type { Logger } from '../Logger.js';
+import type { SanitizeErrorOptions } from './sanitizeError.js';
+/**
+ * React Native's global error hook.
+ *
+ * `ErrorUtils` is undocumented and has been de-facto stable for a decade, which
+ * is the whole risk: it is typed here rather than imported so the library never
+ * depends on a declaration file that may not exist, and every access is
+ * guarded so a runtime without it degrades to doing nothing.
+ */
+export interface ErrorUtilsLike {
+    setGlobalHandler(handler: (error: unknown, isFatal?: boolean) => void): void;
+    getGlobalHandler?(): ((error: unknown, isFatal?: boolean) => void) | undefined;
+}
+/** Metadata keys this handler writes. Add them to a strict key catalog. */
+export declare const ERROR_METADATA_KEYS: readonly ["errorName", "errorMessage", "errorFrames", "errorFrameCount", "errorFramesTruncated", "fatal"];
+/** The message this handler logs. A literal, as the lint rule requires. */
+export declare const UNCAUGHT_ERROR_MESSAGE = "uncaught error";
+export interface ErrorHandlerOptions extends SanitizeErrorOptions {
+    /** Defaults to the shared `Log`. */
+    readonly logger?: Logger;
+    /** Injected for tests; defaults to the global `ErrorUtils`. */
+    readonly errorUtils?: ErrorUtilsLike;
+    /**
+     * How long a fatal error's flush may take. Default 2000 ms.
+     *
+     * This is the crash path and the only chance the buffered entries get, so it
+     * is worth more than a normal flush — but it runs on the JS thread while the
+     * app is already dying, and a watchdog kill loses the log entirely.
+     */
+    readonly fatalFlushMs?: number;
+    /** Subsystem to tag the entry with. */
+    readonly subsystem?: string;
+    /**
+     * Pass the error on to whatever handler was installed before. Default true:
+     * suppressing it removes the dev RedBox and, in production, converts a crash
+     * into a silently broken app.
+     */
+    readonly chain?: boolean;
+}
+/** Undoes an install. Idempotent; safe to call after another handler took over. */
+export type Uninstall = () => void;
+/**
+ * Logs uncaught errors, flushes on fatal ones, and hands the error onward.
+ *
+ * The flush is the reason this exists. A crash is precisely when the buffered
+ * entries explaining it are still in memory, and precisely when nothing will
+ * come along later to write them.
+ *
+ * Nothing about the error is trusted — see {@link sanitizeError}. What reaches
+ * the log is a built-in class name, a redacted message outside dev, and stack
+ * positions in files whose names were already known.
+ */
+export declare function installErrorHandler(options?: ErrorHandlerOptions): Uninstall;
+//# sourceMappingURL=errorHandler.d.ts.map

package/lib/typescript/src/integrations/errorHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorHandler.d.ts","sourceRoot":"","sources":["../../../../src/integrations/errorHandler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAW,CAAC;AAGxC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAiB,CAAC;AAG5D;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,gBAAgB,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAC;IAC7E,gBAAgB,CAAC,IACf,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CAC7D;AAED,2EAA2E;AAC3E,eAAO,MAAM,mBAAmB,2GAOtB,CAAC;AAEX,2EAA2E;AAC3E,eAAO,MAAM,sBAAsB,mBAAmB,CAAC;AAEvD,MAAM,WAAW,mBAAoB,SAAQ,oBAAoB;IAC/D,oCAAoC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC;IACrC;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,uCAAuC;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAID,mFAAmF;AACnF,MAAM,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC;AAEnC;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAqF5E"}

package/lib/typescript/src/integrations/sanitizeError.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Turning a thrown value into something a log file is allowed to contain.
+ *
+ * An uncaught error is the one place the logger handles a string it did not
+ * construct, cannot see the provenance of, and did not put through the privacy
+ * layer. `new Error(\`no chart for ${patient.mrn}\`)` is an entirely ordinary
+ * line of application code, and its message reaches here verbatim. So nothing
+ * from the error is trusted: the class name is allowlisted down to a fixed
+ * token, the message is dropped outside dev, and stack frames are reduced to a
+ * position in a file whose name we already knew.
+ *
+ * The result is safe enough to mark `pub()`, which is the point — sanitising is
+ * what earns an error the right to be rendered.
+ */
+/** What an unrecognised error class is reported as. */
+export declare const UNKNOWN_ERROR_NAME = "Error";
+/** What a stack frame in a file we cannot vouch for is reported as. */
+export declare const REDACTED_FRAME = "<frame>";
+/** What an error message is reported as outside a dev build. */
+export declare const REDACTED_MESSAGE = "<redacted>";
+/** What a thrown non-Error is reported as. */
+export declare const NON_ERROR_THROWN = "<non-error>";
+/**
+ * Bundle basenames a frame may be named after.
+ *
+ * A frame is only useful if you can find the file, and the files an app ships
+ * are known in advance. Everything else — a path from `node_modules`, a
+ * `blob:` URL, a filename built at runtime — is reported positionally instead.
+ * R3's point stands on its own: a basename can be perfectly regex-valid and
+ * still be `patient-12345.js`.
+ */
+export declare const DEFAULT_BUNDLE_NAMES: readonly string[];
+/** Frames beyond this are dropped; the count of what was dropped is kept. */
+export declare const DEFAULT_MAX_FRAMES = 12;
+/**
+ * How much of a stack is read at all, regardless of how many frames are kept.
+ *
+ * `stack` is a property of an object someone threw, which means its size is
+ * chosen by whatever threw it and not by any engine limit. Splitting it whole
+ * to count frames we then discard hands an arbitrary allocation to the one
+ * code path that runs while the app is already crashing. A real Hermes or V8
+ * stack is a few kilobytes and a few dozen lines; anything past these bounds
+ * is reported as truncated rather than read.
+ */
+export declare const MAX_STACK_CHARS: number;
+export declare const MAX_STACK_LINES = 256;
+/**
+ * How much of a single line the frame pattern is run against.
+ *
+ * Capping the whole stack is not enough on its own. {@link FRAME_TAIL} ends in
+ * `$`, and its leading `[^\s()]+` backtracks: given one very long line with no
+ * separator in it, the engine retries from every offset and the match becomes
+ * quadratic. A 64 KB line took four seconds to reject — inside the crash
+ * handler. The pattern is anchored at the end, so the last kilobyte decides it
+ * for any line that could really be a frame.
+ */
+export declare const MAX_FRAME_LINE_CHARS = 1024;
+export interface SanitizedError {
+    /** An allowlisted built-in name, or `'Error'`. */
+    readonly name: string;
+    /** The real message in a dev build; {@link REDACTED_MESSAGE} otherwise. */
+    readonly message: string;
+    /** Sanitised frames, newest first, at most `maxFrames` of them. */
+    readonly frames: readonly string[];
+    /** How many frames were found in the part of the stack that was read. */
+    readonly frameCount: number;
+    /**
+     * The stack was longer than {@link MAX_STACK_CHARS} or
+     * {@link MAX_STACK_LINES} and was not read to the end, so `frameCount` is a
+     * floor rather than a total.
+     */
+    readonly framesTruncated: boolean;
+}
+export interface SanitizeErrorOptions {
+    readonly bundleNames?: readonly string[];
+    readonly maxFrames?: number;
+}
+/** @internal Test/CI hook — non-empty only once the dev reveal branch ran. */
+export declare function __errorRevealBranchSentinel(): string;
+/**
+ * Reduces a thrown value to a name, a message, and a list of positions.
+ *
+ * Total by construction: every branch that could throw — a getter on `message`,
+ * a `stack` that is not a string, a `name` that is a Symbol — ends at a fixed
+ * token rather than propagating. An error handler that throws while reporting
+ * an error takes the crash report with it.
+ */
+export declare function sanitizeError(thrown: unknown, options?: SanitizeErrorOptions): SanitizedError;
+//# sourceMappingURL=sanitizeError.d.ts.map

package/lib/typescript/src/integrations/sanitizeError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitizeError.d.ts","sourceRoot":"","sources":["../../../../src/integrations/sanitizeError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAsBH,uDAAuD;AACvD,eAAO,MAAM,kBAAkB,UAAU,CAAC;AAE1C,uEAAuE;AACvE,eAAO,MAAM,cAAc,YAAY,CAAC;AAExC,gEAAgE;AAChE,eAAO,MAAM,gBAAgB,eAAe,CAAC;AAE7C,8CAA8C;AAC9C,eAAO,MAAM,gBAAgB,gBAAgB,CAAC;AAE9C;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAKjD,CAAC;AAEF,6EAA6E;AAC7E,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,QAAY,CAAC;AACzC,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAeD,8EAA8E;AAC9E,wBAAgB,2BAA2B,IAAI,MAAM,CAEpD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,oBAAoB,GAC7B,cAAc,CAwChB"}

package/lib/typescript/src/levels.d.ts

@@ -0,0 +1,9 @@
+import type { LogLevel } from './types.js';
+/** Numeric severity order; also the codes that cross the bridge. */
+export declare const LEVEL_ORDER: Record<LogLevel, number>;
+export declare function levelAtLeast(level: LogLevel, minimum: LogLevel): boolean;
+/** Fixed-width 5-character tags, byte-identical to SwiftLogger's. */
+export declare const LEVEL_TAG: Record<LogLevel, string>;
+/** Uppercase names used by the JSON formatter (SwiftLogger rawValue parity). */
+export declare const LEVEL_NAME: Record<LogLevel, string>;
+//# sourceMappingURL=levels.d.ts.map

package/lib/typescript/src/levels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"levels.d.ts","sourceRoot":"","sources":["../../../src/levels.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAS,CAAC;AAExC,oEAAoE;AACpE,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAOhD,CAAC;AAEF,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,GAAG,OAAO,CAExE;AAED,qEAAqE;AACrE,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAO9C,CAAC;AAEF,gFAAgF;AAChF,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAO/C,CAAC"}

package/lib/typescript/src/metadata.d.ts

@@ -0,0 +1,23 @@
+import type { LogMetadata } from './types.js';
+/**
+ * Copies caller metadata with per-property isolation, for the one place a
+ * snapshot is genuinely required: a scope's defaults, captured once at
+ * construction so later mutation of the caller's object cannot change what
+ * future messages report.
+ *
+ * Caller objects are untrusted. A Proxy with a throwing `ownKeys` trap
+ * yields `undefined` — the whole object is dropped, payload-free. A throwing
+ * property getter keeps the key but substitutes {@link UNREADABLE_VALUE}, so
+ * redaction still sees the key, rejects it, and counts it; dropping the key
+ * here would make it disappear from `droppedMetadataCount` entirely.
+ *
+ * The copy has a null prototype. Plain-object assignment would route a
+ * `__proto__` key through `Object.prototype`'s legacy setter, silently
+ * losing that value and letting a JS caller reshape the snapshot.
+ *
+ * Call-site metadata is deliberately NOT snapshotted — it goes to
+ * `redactMetadata` as a source so its keys are validated before any value
+ * is read.
+ */
+export declare function safeSnapshotMetadata(metadata: LogMetadata | undefined): LogMetadata | undefined;
+//# sourceMappingURL=metadata.d.ts.map

package/lib/typescript/src/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../../src/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAS,CAAC;AAG3C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,WAAW,GAAG,SAAS,GAChC,WAAW,GAAG,SAAS,CA0BzB"}

package/lib/typescript/src/privacy.d.ts

@@ -0,0 +1,103 @@
+import type { LogMetadata, LogPrimitive, LogValue, RedactedMetadata } from './types.js';
+/**
+ * The privacy layer, deliberately a single module.
+ *
+ * Marker inspection and redaction live together so that payload recovery
+ * stays closure-private. If `inspectMarker` were exported, anyone could deep
+ * import the compiled module and read back a `priv()` payload in production,
+ * which would defeat the whole no-reveal contract regardless of what the
+ * package entry point re-exports. Nothing here that can return a payload
+ * crosses the module boundary.
+ */
+/** What a redacted value renders as in a log line. */
+export declare const PRIVATE_PLACEHOLDER = "<private>";
+/** Source text of the key rule, for callers that want their own RegExp. */
+export declare const METADATA_KEY_PATTERN_SOURCE = "^[A-Za-z0-9._-]{1,64}$";
+/** Reserved key carrying the fixed diagnostic: how many entries this call
+ * dropped. A count only — never which keys, never why, never the values. */
+export declare const DROPPED_COUNT_KEY = "droppedMetadataCount";
+/** Upper bound on catalog size. A hostile or accidental infinite iterable
+ * must not be able to hang the JS thread inside a logging config call. */
+export declare const MAX_CATALOG_SIZE = 4096;
+declare const publicBrand: unique symbol;
+declare const privateBrand: unique symbol;
+/** A value explicitly marked safe to render. Opaque: the payload lives in a
+ * module-private WeakMap, never on the object. */
+export interface PublicValue {
+    readonly [publicBrand]: true;
+}
+/** A value explicitly marked sensitive. Renders as `<private>` outside dev. */
+export interface PrivateValue {
+    readonly [privateBrand]: true;
+}
+/**
+ * Mark a value safe to render even under a `'private'` privacy default.
+ *
+ * The payload is validated here AND again at emit: `pub(patient as any)`
+ * must not smuggle an object past the primitive check. An invalid payload
+ * does not throw — logging never crashes the caller — it produces a marker
+ * that is dropped at emit and counted in the fixed diagnostic.
+ */
+export declare function pub(value: LogPrimitive): PublicValue;
+/** Mark a value sensitive: renders as `<private>` outside dev builds, even
+ * under a `'public'` privacy default. Same fail-closed validation as `pub`. */
+export declare function priv(value: LogPrimitive): PrivateValue;
+/**
+ * Stands in for a value that could not be read when a snapshot was taken —
+ * a getter that threw while a scope was being constructed.
+ *
+ * It is registered as an invalid marker, so redaction drops it and counts
+ * it like any other rejected value. Without it the key would vanish at
+ * snapshot time and never appear in `droppedMetadataCount`, which is the
+ * one thing a silent drop must never do. It carries no payload.
+ */
+export declare const UNREADABLE_VALUE: LogValue;
+/** @internal Test/CI hook — non-empty only once the dev reveal branch ran.
+ * Returns a build-time marker, never a payload. */
+export declare function __revealBranchSentinel(): string;
+export type PrivacyDefault = 'public' | 'private';
+export interface PrivacySettings {
+    /** `'private'` redacts bare values outside dev; `'public'` renders them. */
+    readonly privacyDefault: PrivacyDefault;
+    /** Kill switch: redact every value regardless of marker or build type. */
+    readonly redactAll: boolean;
+    /** Approved metadata keys. Undefined means "no catalog configured". */
+    readonly keyCatalog: ReadonlySet<string> | undefined;
+}
+/**
+ * Coerce a caller-supplied privacy default. TypeScript's union is not a
+ * runtime guarantee — JS callers, JSON config, and `any` all reach here — so
+ * anything that is not exactly `'public'` or `'private'` resolves to
+ * `'private'`. Ambiguity must never resolve toward disclosure.
+ */
+export declare function normalizePrivacyDefault(value: unknown): PrivacyDefault;
+/**
+ * Build a catalog from caller-supplied input without trusting it. A
+ * non-iterable, an iterator that throws mid-way, a non-string entry, or an
+ * iterable longer than {@link MAX_CATALOG_SIZE} all yield an empty set: the
+ * caller's tighten-only intent is honored in the safest possible direction,
+ * and a runaway iterable cannot hang the JS thread.
+ */
+export declare function buildCatalog(keys: unknown): Set<string>;
+/**
+ * Resolve caller metadata into what destinations may see.
+ *
+ * Takes metadata as ordered sources — a scope's defaults followed by the
+ * call site's — rather than a pre-merged object. Merging eagerly would read
+ * every value before any key was checked, which is exactly what this
+ * function exists to avoid: precedence is settled per key first, then the
+ * winning key is validated, and only a key that survives has its value read.
+ * A getter behind a malformed, reserved, or unapproved key therefore never
+ * runs, and neither does a getter the call site overrode.
+ *
+ * Every rejection — bad key, throwing getter, unsupported value —
+ * increments one count. The count is all that is reported: the diagnostic
+ * itself must not become the leak.
+ *
+ * The result is a frozen null-prototype object. A source whose keys cannot
+ * be enumerated at all (a Proxy with a throwing `ownKeys` trap) contributes
+ * nothing, since there is no key that could be safely counted or described.
+ */
+export declare function redactMetadata(scopeMetadata: LogMetadata | undefined, callSiteMetadata: LogMetadata | undefined, settings: PrivacySettings): RedactedMetadata | undefined;
+export {};
+//# sourceMappingURL=privacy.d.ts.map

package/lib/typescript/src/privacy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"privacy.d.ts","sourceRoot":"","sources":["../../../src/privacy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,gBAAgB,EACjB,MAAM,YAAS,CAAC;AAEjB;;;;;;;;;GASG;AAEH,sDAAsD;AACtD,eAAO,MAAM,mBAAmB,cAAc,CAAC;AAmB/C,2EAA2E;AAC3E,eAAO,MAAM,2BAA2B,2BAA2B,CAAC;AAMpE;4EAC4E;AAC5E,eAAO,MAAM,iBAAiB,yBAAyB,CAAC;AAExD;0EAC0E;AAC1E,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC,OAAO,CAAC,MAAM,WAAW,EAAE,OAAO,MAAM,CAAC;AACzC,OAAO,CAAC,MAAM,YAAY,EAAE,OAAO,MAAM,CAAC;AAE1C;kDACkD;AAClD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,CAAC,WAAW,CAAC,EAAE,IAAI,CAAC;CAC9B;AAED,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC;CAC/B;AA6CD;;;;;;;GAOG;AACH,wBAAgB,GAAG,CAAC,KAAK,EAAE,YAAY,GAAG,WAAW,CAQpD;AAED;+EAC+E;AAC/E,wBAAgB,IAAI,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY,CAQtD;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAI3B,CAAC;AA4CL;mDACmD;AACnD,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAID,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,SAAS,CAAC;AAElD,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;CACtD;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAEtE;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,CAmBvD;AAmED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAC5B,aAAa,EAAE,WAAW,GAAG,SAAS,EACtC,gBAAgB,EAAE,WAAW,GAAG,SAAS,EACzC,QAAQ,EAAE,eAAe,GACxB,gBAAgB,GAAG,SAAS,CA8C9B"}

package/lib/typescript/src/specs/FileSink.nitro.d.ts

@@ -0,0 +1,131 @@
+import type { HybridObject } from 'react-native-nitro-modules';
+/**
+ * Rotation and retention policy for one log file.
+ *
+ * All numeric fields are validated in TypeScript (finite safe integers,
+ * positive sizes, bounded counts) AND re-clamped natively before integer
+ * conversion — a NaN/Infinity/negative must never trap a Swift/Kotlin cast.
+ */
+export interface RotationConfig {
+    /** Soft threshold; overshoot bounded by one batch. */
+    maxFileSizeBytes: number;
+    /** Archives to retain by count; 0 keeps none. */
+    maxArchivedFilesCount: number;
+    /** Rotate the current file once this old, regardless of size. */
+    maxFileAgeSeconds?: number;
+    /** Gzip archives as they rotate out. */
+    compressArchives: boolean;
+    /** Delete archives older than this even if under the count cap. */
+    maxArchiveAgeSeconds?: number;
+    /** Bound on current file + all archives combined. */
+    maxTotalLogBytes?: number;
+}
+/** Why an appendBatch was not accepted. */
+export type RejectReason = 'full' | 'staleGeneration' | 'closed' | 'failed';
+/**
+ * Snapshot of sink health. MUST be served from atomics / a short non-I/O
+ * lock — never from the writer queue — so a paused Batcher can poll it while
+ * the writer is stalled on disk.
+ *
+ * Loss fields are per-handle observed counters (monotonic writer totals with
+ * per-handle cursors underneath); observing a loss here does NOT acknowledge
+ * it — acknowledgement happens only after the consolidated loss notice has
+ * durably flushed.
+ */
+export interface SinkStatus {
+    queuedBytes: number;
+    lostBytes: number;
+    lostEntries: number;
+    /** Payload-free degradation bitmask: rotation|gzip|prune|sidecar|protection. */
+    degraded: number;
+}
+export interface AppendResult {
+    accepted: boolean;
+    /** Present only when accepted is false. */
+    rejectReason?: RejectReason;
+    queuedBytes: number;
+    lostBytes: number;
+    lostEntries: number;
+    degraded: number;
+}
+export interface FlushOutcome {
+    /** True when every previously accepted byte reached storage and fsync. */
+    durable: boolean;
+    timedOut: boolean;
+    pendingBytes: number;
+    queuedBytes: number;
+    lostBytes: number;
+    lostEntries: number;
+    degraded: number;
+}
+export interface ClearOutcome {
+    deletedCount: number;
+    failedPaths: string[];
+    /** False when any artifact survived or the deadline elapsed. */
+    durable: boolean;
+    /**
+     * Whether the writer came back with a usable file afterwards.
+     *
+     * Separate from `durable` because they are separate facts and the caller
+     * needs both. A purge can delete everything it was asked to — `durable` —
+     * and still fail to reopen, on a directory that has become unwritable or a
+     * volume that filled. Resuming on `durable` alone hands records to a writer
+     * with nowhere to put them: every one is accepted, then rejected as
+     * `staleGeneration`, then dropped.
+     *
+     * Resume only when both are true. `durable && !rebound` means the deletion
+     * is genuinely complete — which is what a compliance caller asked — but the
+     * destination must stay fenced until an explicit retry gets a live file back.
+     */
+    rebound: boolean;
+}
+/**
+ * Dumb native file sink. All intelligence (batching, backpressure, drop
+ * accounting, formatting, redaction) lives in TypeScript; this object only
+ * appends pre-batched text, rotates, compresses, and reports counters.
+ *
+ * One JS FileDestination = one FileSink handle; handles for the same
+ * canonical path share one process-global writer (registry, refcounted,
+ * generation-fenced). Batch = atomic loss unit.
+ */
+export interface FileSink extends HybridObject<{
+    ios: 'swift';
+    android: 'kotlin';
+}> {
+    readonly defaultLogDirectory: string;
+    /**
+     * Throws on open failure OR on config conflict with an existing writer.
+     *
+     * `lineFramed` declares that every batch handed to `appendBatch` contains
+     * whole records terminated by `\n`, with no raw newline inside a record.
+     * Only then may the startup scan trim an incomplete trailing record: with
+     * opaque multi-line text a writer cannot tell a torn record from an
+     * intentional one, and trimming would destroy good data. Absent — the
+     * default for a custom formatter that does not declare `framing: 'line'` —
+     * the file is left exactly as the crash left it and recovery is reduced.
+     */
+    open(path: string, rotation?: RotationConfig, lineFramed?: boolean): void;
+    /**
+     * Enqueue only — never performs I/O inline. Atomic accept/reject BEFORE
+     * enqueue against the hard shared payload cap; accepted bytes stay
+     * reserved until terminal write completion. entryCount travels with the
+     * queued item for exact loss accounting.
+     */
+    appendBatch(batch: string, entryCount: number): AppendResult;
+    /** Non-enqueuing health probe; safe to poll while the writer is stalled. */
+    getStatus(): SinkStatus;
+    /** Wall-clock-bounded synchronous drain + fsync. */
+    flush(deadlineMs: number): FlushOutcome;
+    /** Deadline-aware disposal; a hung write cannot block forever. */
+    close(deadlineMs: number): FlushOutcome;
+    /** Active file + archives, newest first. */
+    getLogFilePaths(): string[];
+    /**
+     * Registry-serialized purge of the COMPLETE artifact set (current file,
+     * sidecar, archives, gzip temporaries, staging/recovery files). Bumps the
+     * writer generation; the invoking handle rebinds only after durable
+     * success. Reached via the Logger-layer purge flow, never called ad hoc.
+     */
+    clearLogs(deadlineMs: number): ClearOutcome;
+}
+//# sourceMappingURL=FileSink.nitro.d.ts.map