react-native-nitro-logger 0.1.0

package/src/destinations/NativeConsoleDestination.ts

@@ -0,0 +1,220 @@
+import type { LogEntry, LogLevel } from '../types';
+import type { LogDestination } from './types';
+import type { LogFormatter } from '../formatters/types';
+import { DefaultFormatter } from '../formatters/DefaultFormatter';
+import { LEVEL_ORDER } from '../levels';
+
+/**
+ * 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;
+}
+
+const DEFAULT_BATCH_SIZE = 64;
+const DEFAULT_FLUSH_INTERVAL_MS = 100;
+const DEFAULT_MAX_PENDING = 1000;
+
+/**
+ * Number of consecutive failed `logBatch` calls before the destination stops
+ * trying. A native sink that is throwing every time will not start working
+ * because we asked once more, and a try/catch per drain forever is a cost the
+ * app pays for nothing.
+ */
+const FAILURE_LIMIT = 3;
+
+/**
+ * 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 class NativeConsoleDestination implements LogDestination {
+  readonly label: string;
+  readonly minimumLevel?: LogLevel;
+
+  private readonly sink: NativeConsoleSinkLike;
+  private readonly formatter: LogFormatter;
+  private readonly batchSize: number;
+  private readonly flushIntervalMs: number;
+  private readonly maxPending: number;
+
+  private levels: number[] = [];
+  private messages: string[] = [];
+  private timer: ReturnType<typeof setTimeout> | undefined;
+  private disposed = false;
+  private failures = 0;
+  private droppedEntries = 0;
+
+  constructor(
+    sink: NativeConsoleSinkLike,
+    options?: NativeConsoleDestinationOptions
+  ) {
+    this.sink = sink;
+    this.label = options?.label ?? 'native-console';
+    this.minimumLevel = options?.minimumLevel;
+    this.formatter = options?.formatter ?? new DefaultFormatter();
+    this.batchSize = positive(options?.batchSize, DEFAULT_BATCH_SIZE);
+    this.flushIntervalMs = positive(
+      options?.flushIntervalMs,
+      DEFAULT_FLUSH_INTERVAL_MS
+    );
+    this.maxPending = positive(options?.maxPendingEntries, DEFAULT_MAX_PENDING);
+
+    // An empty subsystem is legal and produces a logger nobody can find in
+    // Console; the native side substitutes the bundle identifier for it.
+    this.sink.install(options?.subsystem ?? '', options?.category ?? 'log');
+  }
+
+  /**
+   * 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 {
+    return !this.disposed && this.failures < FAILURE_LIMIT;
+  }
+
+  /** Entries this destination never handed to the platform log. */
+  dropped(): number {
+    return this.droppedEntries;
+  }
+
+  write(entry: LogEntry): void {
+    if (!this.isEnabled) return;
+
+    if (this.messages.length >= this.maxPending) {
+      // Drop-newest, matching the Batcher. Under a burst the oldest entries
+      // are the ones that explain how it started, which is what a reader is
+      // looking for; keeping the newest would leave only the aftermath.
+      this.droppedEntries += 1;
+      return;
+    }
+
+    // Render first, then append both halves together. The two arrays are
+    // parallel and are read by index natively, so pushing the level before the
+    // message that might not arrive leaves them one apart — and from that point
+    // on every entry in the batch is logged at its predecessor's severity. The
+    // Logger catches a throwing destination and carries on, which is exactly
+    // what would let the misalignment survive unnoticed.
+    let rendered: string;
+    try {
+      rendered = this.formatter.format(entry);
+    } catch {
+      // Not counted against the sink's failure run: the sink is fine, the
+      // formatter is not, and disabling the channel over someone else's bug
+      // would take the console down for every entry a working formatter could
+      // still have rendered.
+      this.droppedEntries += 1;
+      return;
+    }
+
+    this.levels.push(LEVEL_ORDER[entry.level]);
+    this.messages.push(rendered);
+
+    if (this.messages.length >= this.batchSize) {
+      this.drain();
+      return;
+    }
+    this.arm();
+  }
+
+  /**
+   * 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 {
+    this.drain();
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    // Flush before the flag, not after: entries buffered up to this moment
+    // were accepted, and disposing is not a reason to drop them.
+    this.drain();
+    this.disposed = true;
+    this.cancel();
+  }
+
+  private drain(): void {
+    this.cancel();
+    if (this.messages.length === 0) return;
+
+    const levels = this.levels;
+    const messages = this.messages;
+    this.levels = [];
+    this.messages = [];
+
+    if (this.disposed) return;
+
+    try {
+      this.sink.logBatch(levels, messages);
+      this.failures = 0;
+    } catch {
+      // Payload-free: whatever the native side threw is not worth risking on
+      // the way back through a logger. The batch is gone either way, so it is
+      // counted rather than retried — replaying it against a sink that just
+      // rejected it only doubles the chance of the same failure.
+      this.failures += 1;
+      this.droppedEntries += messages.length;
+    }
+  }
+
+  private arm(): void {
+    if (this.timer !== undefined) return;
+    this.timer = setTimeout(() => {
+      this.timer = undefined;
+      this.drain();
+    }, this.flushIntervalMs);
+  }
+
+  private cancel(): void {
+    if (this.timer === undefined) return;
+    clearTimeout(this.timer);
+    this.timer = undefined;
+  }
+}
+
+/** Finite positive integers only; anything else falls back. */
+function positive(value: number | undefined, fallback: number): number {
+  if (value === undefined) return fallback;
+  if (!Number.isSafeInteger(value) || value < 1) return fallback;
+  return value;
+}

package/src/destinations/types.ts

@@ -0,0 +1,19 @@
+import type { LogEntry, LogLevel } from '../types';
+
+/**
+ * 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;
+}

package/src/formatters/DefaultFormatter.ts

@@ -0,0 +1,150 @@
+import type { LogEntry } from '../types';
+import type { LogFormatter } from './types';
+import { LEVEL_TAG } from '../levels';
+import { formatTime } from './timestamp';
+
+/**
+ * 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 class DefaultFormatter implements LogFormatter {
+  format(entry: LogEntry): string {
+    let tags = '';
+    if (entry.correlation !== undefined) {
+      tags += `[${escapeControls(entry.correlation)}] `;
+    }
+    if (entry.subsystem !== undefined) {
+      tags += `[${escapeControls(entry.subsystem)}] `;
+    }
+
+    let body = `${tags}${formatMessage(entry.message)}`;
+    if (entry.metadata) {
+      const metadata = entry.metadata;
+      const keys = Object.keys(metadata).sort();
+      if (keys.length > 0) {
+        const pairs = keys
+          .map(
+            (k) => `${escapeControls(k)}=${escapeControls(String(metadata[k]))}`
+          )
+          .join(', ');
+        body += ` {${pairs}}`;
+      }
+    }
+
+    return `${LEVEL_TAG[entry.level]} | ${formatTime(entry.timestamp)} | ${body}`;
+  }
+}
+
+/**
+ * Blanks the tag and timestamp columns, so a continuation line lines up under
+ * the message and cannot be read as a record of its own.
+ *
+ *     ERROR | 12:15:30.842 | Unhandled TypeError
+ *           |              | at foo (bundle.js:1:2)
+ *
+ * Five spaces for the level tag, twelve for `HH:mm:ss.SSS`, and the two
+ * separators. A real record always carries a known tag and a timestamp made
+ * of digits, so a blank in either column cannot be mistaken for one.
+ */
+const CONTINUATION = `${' '.repeat(5)} | ${' '.repeat(12)} | `;
+
+/**
+ * Renders the message, keeping its lines but never letting one start a record.
+ *
+ * SwiftLogger leaves `message` completely alone, and this package did too
+ * until review pointed out that matching the reference is not the same as
+ * being safe. The forgery is the one escaping the structured fields prevents:
+ * an error message or an interpolated string carrying
+ * `"\nERROR | 00:00:00.000 | patient discharged"` writes a line a reader
+ * cannot tell from a real one. Reachability is not theoretical —
+ * `no-dynamic-message` is what normally keeps arbitrary text out of this
+ * field, and it cannot see a logger wired through a function call.
+ *
+ * Escaping newlines outright would fix it and ruin the crash handler, which
+ * logs stack traces through this field on purpose. Indenting continuation
+ * lines keeps them readable and still leaves nothing that parses as a header.
+ *
+ * This is a deliberate parity difference; docs/PARITY.md records it.
+ */
+function formatMessage(message: string): string {
+  // Four things besides \n break a line. A bare \r does, and can also drag
+  // the cursor back over what was already printed. U+0085 (NEL) does for any
+  // Unicode-aware reader. U+2028 and U+2029 do for anything treating this as
+  // JavaScript-flavoured text.
+  return message
+    .split(/\r\n|[\n\r\u0085\u2028\u2029]/)
+    .map(escapeControls)
+    .join(`\n${CONTINUATION}`);
+}
+
+/**
+ * Renders C0, DEL, C1, and the Unicode line/paragraph separators as escapes.
+ *
+ * C1 (U+0080–U+009F) matters as much as C0 here and is easy to forget:
+ * U+009B is a single-character CSI, so a terminal will happily read what
+ * follows it as a cursor-movement or erase sequence, and U+0085 is NEL,
+ * which Unicode-aware readers treat as a line break.
+ *
+ * U+2028 and U+2029 are here for exactly the reason U+0085 is. They are not
+ * control characters and a plain `\n`-splitting reader ignores them, but a
+ * JavaScript one does not: `^` and `$` under the `m` flag treat both as line
+ * terminators, so a log viewer written in JS — the likely kind for this
+ * package — sees a line break where a terminal sees none. That asymmetry is
+ * worse than either alone, because the forged line is invisible in the tool
+ * someone checks the raw file with.
+ *
+ * This layout is one entry per line, so a newline inside a *structured* field
+ * lets whoever supplied that field forge whole log entries. A correlation ID,
+ * a subsystem, or a metadata key or value can all arrive from a request
+ * header, a username, or a URL; without this, `"a\nERROR | 00:00:00.000 | "`
+ * writes a convincing fake line into the log, and the reader has no way to
+ * tell it from a real one.
+ *
+ * The message takes a different route — see {@link formatMessage} — because
+ * it has to stay multi-line. Everything else is escaped outright.
+ *
+ * Clean fields — essentially all of them — are scanned once and returned
+ * whole, so this costs nothing in the normal case.
+ */
+function escapeControls(field: string): string {
+  // eslint-disable-next-line no-control-regex
+  if (!/[\u0000-\u001F\u007F-\u009F\u2028\u2029]/.test(field)) return field;
+
+  let out = '';
+  for (const character of field) {
+    switch (character) {
+      case '\n':
+        out += '\\n';
+        break;
+      case '\r':
+        out += '\\r';
+        break;
+      case '\t':
+        out += '\\t';
+        break;
+      default: {
+        const code = character.codePointAt(0)!;
+        out +=
+          code < 0x20 ||
+          (code >= 0x7f && code <= 0x9f) ||
+          code === 0x2028 ||
+          code === 0x2029
+            ? `\\u{${code.toString(16).toUpperCase()}}`
+            : character;
+      }
+    }
+  }
+  return out;
+}

package/src/formatters/JsonLinesFormatter.ts

@@ -0,0 +1,195 @@
+import type { LogEntry, LogPrimitive, RedactedMetadata } from '../types';
+import type { LogFormatter } from './types';
+import { LEVEL_NAME } from '../levels';
+import { utf8Length } from '../utf8';
+
+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;
+}
+
+/** Instants JavaScript can represent as a Date but not as ISO 8601. */
+const MAX_ISO_MS = 8.64e15;
+
+/**
+ * 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 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' as const;
+
+  private readonly timestampStyle: JsonTimestampStyle;
+
+  constructor(options: JsonLinesFormatterOptions = {}) {
+    this.timestampStyle = options.timestampStyle ?? 'iso8601';
+  }
+
+  format(entry: LogEntry): string {
+    return this.render(entry, entry.message, entry.metadata, false);
+  }
+
+  /**
+   * 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 {
+    const full = this.format(entry);
+    if (utf8Length(full) <= maxBytes) return full;
+
+    // Metadata first: a dropped field costs the reader one fact, whereas a
+    // shortened message can cost them the sentence that explains the others.
+    const keys = entry.metadata ? Object.keys(entry.metadata).sort() : [];
+    for (let keep = keys.length - 1; keep >= 0; keep -= 1) {
+      const subset: Record<string, LogPrimitive> = {};
+      for (const key of keys.slice(0, keep)) {
+        subset[key] = entry.metadata![key]!;
+      }
+      const candidate = this.render(
+        entry,
+        entry.message,
+        keep === 0 ? undefined : subset,
+        true
+      );
+      if (utf8Length(candidate) <= maxBytes) return candidate;
+    }
+
+    // Then the message, by code points so a surrogate pair is never split
+    // into a lone half. Escaping means a code point can cost anywhere from
+    // one to twelve bytes, so the fit is found by measuring whole rendered
+    // records rather than by arithmetic on the message alone.
+    const points = Array.from(entry.message);
+    let low = 0;
+    let high = points.length;
+    while (low < high) {
+      const mid = Math.ceil((low + high) / 2);
+      const candidate = this.render(
+        entry,
+        points.slice(0, mid).join(''),
+        undefined,
+        true
+      );
+      if (utf8Length(candidate) <= maxBytes) low = mid;
+      else high = mid - 1;
+    }
+    return this.render(entry, points.slice(0, low).join(''), undefined, true);
+  }
+
+  private render(
+    entry: LogEntry,
+    message: string,
+    metadata: RedactedMetadata | undefined,
+    truncated: boolean
+  ): string {
+    let json = '{"timestamp":';
+    json += this.renderTimestamp(entry.timestamp);
+    json += ',"level":' + JSON.stringify(LEVEL_NAME[entry.level]);
+    json += ',"message":' + JSON.stringify(message);
+
+    if (entry.correlation !== undefined) {
+      json += ',"correlation":' + JSON.stringify(entry.correlation);
+    }
+    if (entry.subsystem !== undefined) {
+      json += ',"subsystem":' + JSON.stringify(entry.subsystem);
+    }
+
+    if (metadata) {
+      const keys = Object.keys(metadata).sort();
+      if (keys.length > 0) {
+        json += ',"metadata":{';
+        for (let i = 0; i < keys.length; i += 1) {
+          if (i > 0) json += ',';
+          json +=
+            JSON.stringify(keys[i]) + ':' + renderValue(metadata[keys[i]!]!);
+        }
+        json += '}';
+      }
+    }
+
+    if (truncated) json += ',"truncated":true';
+    return json + '}';
+  }
+
+  private renderTimestamp(epochMs: number): string {
+    if (this.timestampStyle === 'epochSeconds') {
+      return Number.isFinite(epochMs) ? String(epochMs / 1000) : '0';
+    }
+    // `toISOString` throws past the representable range, and a formatter that
+    // throws takes down the log call that was trying to report a problem.
+    if (!Number.isFinite(epochMs) || Math.abs(epochMs) > MAX_ISO_MS) {
+      return '"1970-01-01T00:00:00.000Z"';
+    }
+    return JSON.stringify(new Date(epochMs).toISOString());
+  }
+}
+
+/**
+ * A metadata value as JSON, keeping its type.
+ *
+ * Non-finite numbers become quoted strings because JSON has no literal for
+ * them, matching what the Swift formatter does. Redaction rejects them long
+ * before this point, so the branch exists to keep a hand-built entry from
+ * producing `NaN` in the middle of a record rather than because it is
+ * reachable through the public API.
+ */
+function renderValue(value: LogPrimitive): string {
+  switch (typeof value) {
+    case 'string':
+      return JSON.stringify(value);
+    case 'boolean':
+      return value ? 'true' : 'false';
+    default:
+      return Number.isFinite(value)
+        ? String(value)
+        : JSON.stringify(String(value));
+  }
+}

package/src/formatters/timestamp.ts

@@ -0,0 +1,12 @@
+/** 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 function formatTime(epochMs: number): string {
+  const date = new Date(epochMs);
+  const hh = String(date.getHours()).padStart(2, '0');
+  const mm = String(date.getMinutes()).padStart(2, '0');
+  const ss = String(date.getSeconds()).padStart(2, '0');
+  const ms = String(date.getMilliseconds()).padStart(3, '0');
+  return `${hh}:${mm}:${ss}.${ms}`;
+}

package/src/formatters/types.ts

@@ -0,0 +1,29 @@
+import type { LogEntry } from '../types';
+
+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;
+}