react-native-nitro-logger 0.1.0

package/lib/module/Logger.js

@@ -0,0 +1,381 @@
+"use strict";
+
+import { ConsoleDestination } from "./destinations/ConsoleDestination.js";
+import { resolveSubsystemLevel } from "./config.js";
+import { levelAtLeast } from "./levels.js";
+import { buildCatalog, normalizePrivacyDefault, redactMetadata } from "./privacy.js";
+import { ScopedLogger } from "./ScopedLogger.js";
+/** A destination is cut off after this many consecutive write failures. */
+const MAX_CONSECUTIVE_FAILURES = 5;
+
+/**
+ * A registered destination plus the label captured once, at registration.
+ * The label is never re-read afterwards: a getter that succeeds during
+ * registration and throws later would otherwise break removal, and failure
+ * accounting needs a stable key or a misbehaving destination can never be
+ * disabled.
+ */
+
+/**
+ * The logger. Access through the `Log` singleton.
+ *
+ * Everything runs on the JS thread, so unlike the Swift original there is no
+ * lock or config-snapshot machinery — plain fields mutated by the fluent
+ * methods are safe by construction.
+ *
+ * Pipeline per message: resolve effective level (exact subsystem → parent
+ * walk → global) → collect destinations passing isEnabled AND minimumLevel →
+ * return BEFORE evaluating a lazy message when none remain → evaluate once,
+ * guarded → prepare metadata (redaction seam; M2 adds privacy wrappers) →
+ * freeze → fan out with per-destination isolation.
+ *
+ * Destinations are treated as untrusted: every property read and call is
+ * guarded so one faulty implementation can neither crash the app nor starve
+ * its siblings.
+ */
+export class Logger {
+  globalMinimum = 'debug';
+  subsystemLevels = new Map();
+  registrations = defaultRegistrations();
+
+  /** Consecutive write-failure counts per destination label. */
+  failureCounts = new Map();
+  disabledLabels = new Set();
+
+  // Privacy state. Every transition tightens; nothing here can be loosened
+  // at runtime, so a compromised or careless call site cannot turn redaction
+  // off in a shipped build.
+  privacyDefaultValue = 'public';
+  privacyDefaultLocked = false;
+  redactAll = false;
+  // ── Privacy ─────────────────────────────────────────────────────────────
+
+  /**
+   * Choose how bare (unmarked) metadata values are treated.
+   *
+   * `'public'` — the OSS default — renders them. `'private'` redacts every
+   * bare value outside dev builds unless wrapped in `pub()`, so a forgotten
+   * wrapper hides data instead of leaking it. Apps handling PHI set
+   * `'private'` in their entry point.
+   *
+   * First call wins; later calls may only tighten (`'public'` → `'private'`).
+   * A request to loosen is ignored, not obeyed. Anything that is not exactly
+   * `'public'` or `'private'` — a JS caller, JSON config, an `any` — resolves
+   * to `'private'`: ambiguity must never resolve toward disclosure.
+   *
+   * `'private'` also makes the metadata key catalog mandatory — see
+   * {@link metadataKeyCatalog}.
+   */
+  privacyDefault(value) {
+    const normalized = normalizePrivacyDefault(value);
+    if (!this.privacyDefaultLocked) {
+      this.privacyDefaultValue = normalized;
+      this.privacyDefaultLocked = true;
+    } else if (normalized === 'private') {
+      this.privacyDefaultValue = 'private';
+    }
+    return this;
+  }
+
+  /** Redact every metadata value from here on, marked or not, dev or not.
+   * One-way: there is no call that undoes it. */
+  redactAllMetadata() {
+    this.redactAll = true;
+    return this;
+  }
+
+  /**
+   * Restrict metadata to an approved set of keys; anything else is dropped
+   * and counted. Rejecting computed keys is not enough on its own — a
+   * literal key like `patient123` is still PHI — so the catalog checks exact
+   * membership at runtime.
+   *
+   * Tighten-only: repeat calls intersect with the existing catalog rather
+   * than replacing it. Mandatory under a `'private'` privacy default, where
+   * an unconfigured catalog approves nothing and all metadata drops.
+   *
+   * Input is not trusted: a non-iterable, a throwing iterator, a non-string
+   * or malformed entry, or an over-long iterable all yield an empty catalog
+   * rather than an exception or a hung JS thread.
+   */
+  metadataKeyCatalog(keys) {
+    const incoming = buildCatalog(keys);
+    if (this.keyCatalog === undefined) {
+      this.keyCatalog = incoming;
+    } else {
+      const intersection = new Set();
+      for (const key of this.keyCatalog) {
+        if (incoming.has(key)) intersection.add(key);
+      }
+      this.keyCatalog = intersection;
+    }
+    return this;
+  }
+  privacySettings() {
+    return {
+      privacyDefault: this.privacyDefaultValue,
+      redactAll: this.redactAll,
+      keyCatalog: this.keyCatalog
+    };
+  }
+
+  // ── Fluent configuration ────────────────────────────────────────────────
+
+  /** Global minimum level; messages below it are discarded. Default 'debug'. */
+  minimumLevel(level) {
+    this.globalMinimum = level;
+    return this;
+  }
+
+  /** Minimum level for a dot-hierarchical subsystem (`network` covers
+   * `network.api` unless the child sets its own). */
+  subsystem(name, level) {
+    this.subsystemLevels.set(name, level);
+    return this;
+  }
+  resetSubsystem(name) {
+    this.subsystemLevels.delete(name);
+    return this;
+  }
+
+  /** Toggle console printing. The console destination's test sink, when set,
+   * keeps receiving lines regardless. */
+  consoleLogging(enabled) {
+    for (const {
+      destination
+    } of this.registrations) {
+      if (destination instanceof ConsoleDestination) {
+        destination.printEnabled = enabled;
+      }
+    }
+    return this;
+  }
+
+  /**
+   * Register a destination. A *different* destination already holding the
+   * same label is flushed, disposed, and replaced; re-adding an instance
+   * that is already registered is a no-op, because disposing and re-pushing
+   * the same object would leave a live destination in a closed state.
+   */
+  addDestination(destination) {
+    // Identity first: an already-registered instance must not have its label
+    // getter touched again, or the capture-once invariant leaks right here.
+    if (this.registrations.some(r => r.destination === destination)) {
+      return this;
+    }
+    let label;
+    try {
+      label = destination.label;
+    } catch {
+      warnFixed('[Logger] a destination was rejected: its label could not be read');
+      return this;
+    }
+    if (typeof label !== 'string') {
+      warnFixed('[Logger] a destination was rejected: its label is not a string');
+      return this;
+    }
+    this.removeDestination(label);
+    this.registrations.push({
+      destination,
+      label
+    });
+    return this;
+  }
+  removeDestination(label) {
+    const index = this.registrations.findIndex(r => r.label === label);
+    if (index >= 0) {
+      const removed = this.registrations.splice(index, 1)[0];
+      // Guarded separately: a failing flush must not skip dispose, or the
+      // removed destination leaks timers/handles it will never release.
+      try {
+        removed.destination.flush();
+      } catch {
+        // a failing flush must not break reconfiguration
+      }
+      try {
+        removed.destination.dispose();
+      } catch {
+        // a failing dispose must not break reconfiguration
+      }
+    }
+    this.failureCounts.delete(label);
+    this.disabledLabels.delete(label);
+    return this;
+  }
+
+  /** Drain every destination synchronously (bounded per destination). */
+  flush(deadlineMs = 2000) {
+    for (const {
+      destination
+    } of this.registrations) {
+      try {
+        destination.flush(deadlineMs);
+      } catch {
+        // isolation: one failing flush must not stop the others
+      }
+    }
+  }
+
+  // ── Scopes & correlation ────────────────────────────────────────────────
+
+  /** Short-lived random correlation ID — the encouraged way to correlate.
+   * Never derive correlation IDs from patient/visit/record identifiers. */
+  newCorrelationId() {
+    return Math.random().toString(36).slice(2, 10);
+  }
+
+  /** A scoped logger tagging every message with a correlation ID, optional
+   * subsystem, and default metadata. Omit `correlation` to auto-generate. */
+  scoped(correlation, subsystem, metadata) {
+    return new ScopedLogger(this, correlation ?? this.newCorrelationId(), subsystem, metadata);
+  }
+
+  // ── Logging ─────────────────────────────────────────────────────────────
+
+  log(message, options) {
+    this.logMessage(message, options);
+  }
+  verbose(message, metadata, subsystem) {
+    this.logMessage(message, {
+      level: 'verbose',
+      metadata,
+      subsystem
+    });
+  }
+  debug(message, metadata, subsystem) {
+    this.logMessage(message, {
+      level: 'debug',
+      metadata,
+      subsystem
+    });
+  }
+  info(message, metadata, subsystem) {
+    this.logMessage(message, {
+      level: 'info',
+      metadata,
+      subsystem
+    });
+  }
+  warning(message, metadata, subsystem) {
+    this.logMessage(message, {
+      level: 'warning',
+      metadata,
+      subsystem
+    });
+  }
+  error(message, metadata, subsystem) {
+    this.logMessage(message, {
+      level: 'error',
+      metadata,
+      subsystem
+    });
+  }
+
+  /** Marks incomplete work; highest severity so it always surfaces. */
+  todo(message, metadata, subsystem) {
+    this.logMessage(message, {
+      level: 'todo',
+      metadata,
+      subsystem
+    });
+  }
+
+  /** Integration entry point (ScopedLogger, error handler, bridges). */
+  logMessage(message, options) {
+    const level = options?.level ?? 'info';
+    const subsystem = options?.subsystem;
+    const effectiveMinimum = (subsystem !== undefined ? resolveSubsystemLevel(this.subsystemLevels, subsystem) : undefined) ?? this.globalMinimum;
+    if (!levelAtLeast(level, effectiveMinimum)) return;
+
+    // Eligibility BEFORE message evaluation: a lazy thunk must not run when
+    // nothing will receive the entry. isEnabled/minimumLevel may be throwing
+    // getters, so each read is isolated and charged to the stable label.
+    const eligible = [];
+    for (const registration of this.registrations) {
+      const {
+        destination,
+        label
+      } = registration;
+      if (this.disabledLabels.has(label)) continue;
+      try {
+        if (!destination.isEnabled) continue;
+        if (destination.minimumLevel !== undefined && !levelAtLeast(level, destination.minimumLevel)) {
+          continue;
+        }
+      } catch {
+        this.noteFailure(label);
+        continue;
+      }
+      eligible.push(registration);
+    }
+    if (eligible.length === 0) return;
+    let text;
+    try {
+      text = typeof message === 'function' ? message() : message;
+    } catch {
+      // Payload-free by design: the thrown value could contain anything.
+      text = '[Logger] message thunk threw';
+    }
+
+    // Frozen: the same entry fans out to every destination, so a mutating
+    // destination must not change what its siblings receive. Every field is
+    // a primitive or a frozen null-prototype object, so freezing the entry
+    // is enough — nothing reachable from it is mutable.
+    const entry = Object.freeze({
+      timestamp: Date.now(),
+      level,
+      message: text,
+      metadata: redactMetadata(options?.scopeMetadata, options?.metadata, this.privacySettings()),
+      correlation: options?.correlation,
+      subsystem
+    });
+    for (const {
+      destination,
+      label
+    } of eligible) {
+      try {
+        destination.write(entry);
+        this.failureCounts.delete(label);
+      } catch {
+        this.noteFailure(label);
+      }
+    }
+  }
+
+  /** Count a consecutive failure; disable the destination at the threshold.
+   * The diagnostic is fixed text — labels are caller-controlled, so including
+   * one would break the payload-free contract and invite log injection. */
+  noteFailure(label) {
+    const failures = (this.failureCounts.get(label) ?? 0) + 1;
+    this.failureCounts.set(label, failures);
+    if (failures >= MAX_CONSECUTIVE_FAILURES) {
+      this.disabledLabels.add(label);
+      warnFixed('[Logger] a destination was disabled after repeated write failures');
+    }
+  }
+
+  // Deliberately no reset/reconfigure hook. Such a method would be a public
+  // runtime path to loosen every privacy control on the `Log` singleton, and
+  // an `@internal` tag does not remove a method from a JS build. Tests
+  // construct their own `new Logger()` instead.
+}
+function defaultRegistrations() {
+  const console_ = new ConsoleDestination();
+  return [{
+    destination: console_,
+    label: console_.label
+  }];
+}
+
+/** Fixed-text diagnostic; never interpolates caller-controlled data. */
+function warnFixed(message) {
+  try {
+    console.warn(message);
+  } catch {
+    // nothing left to report to
+  }
+}
+
+/** Global shorthand, mirroring SwiftLogger's `Log`. */
+export const Log = new Logger();
+//# sourceMappingURL=Logger.js.map

package/lib/module/Logger.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["ConsoleDestination","resolveSubsystemLevel","levelAtLeast","buildCatalog","normalizePrivacyDefault","redactMetadata","ScopedLogger","MAX_CONSECUTIVE_FAILURES","Logger","globalMinimum","subsystemLevels","Map","registrations","defaultRegistrations","failureCounts","disabledLabels","Set","privacyDefaultValue","privacyDefaultLocked","redactAll","privacyDefault","value","normalized","redactAllMetadata","metadataKeyCatalog","keys","incoming","keyCatalog","undefined","intersection","key","has","add","privacySettings","minimumLevel","level","subsystem","name","set","resetSubsystem","delete","consoleLogging","enabled","destination","printEnabled","addDestination","some","r","label","warnFixed","removeDestination","push","index","findIndex","removed","splice","flush","dispose","deadlineMs","newCorrelationId","Math","random","toString","slice","scoped","correlation","metadata","log","message","options","logMessage","verbose","debug","info","warning","error","todo","effectiveMinimum","eligible","registration","isEnabled","noteFailure","length","text","entry","Object","freeze","timestamp","Date","now","scopeMetadata","write","failures","get","console_","console","warn","Log"],"sourceRoot":"../../src","sources":["Logger.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/ScopedLogger.js

@@ -0,0 +1,70 @@
+"use strict";
+
+import { safeSnapshotMetadata } from "./metadata.js";
+
+/**
+ * A lightweight logger that tags every message with a correlation ID,
+ * optional default subsystem, and default metadata. Direct port of
+ * SwiftLogger's ScopedLogger: immutable, delegates all work to the parent
+ * Logger, nests.
+ *
+ * Metadata semantics: the scope's metadata merges into every message;
+ * call-site keys win on collision (a message reporting `state: 'failed'`
+ * must not be masked by the scope's `state: 'running'`). Child scopes merge
+ * into — never replace — the parent's metadata.
+ */
+export class ScopedLogger {
+  /** Frozen snapshot taken at construction — mutating the object the caller
+   * passed in (or this field) after the fact must not change future logs,
+   * matching SwiftLogger's value semantics. */
+
+  constructor(logger, correlation, subsystem, metadata) {
+    this.logger = logger;
+    this.correlation = correlation;
+    this.subsystem = subsystem;
+    const snapshot = safeSnapshotMetadata(metadata);
+    this.metadata = snapshot ? Object.freeze(snapshot) : undefined;
+  }
+  log(message, level = 'info', metadata) {
+    this.logger.logMessage(message, {
+      level,
+      subsystem: this.subsystem,
+      // Handed over unmerged: redaction settles precedence per key and
+      // validates the winner BEFORE reading it, so a getter behind a
+      // rejected key — or one the call site overrode — never runs. Merging
+      // here would read every value first and defeat that.
+      scopeMetadata: this.metadata,
+      metadata,
+      correlation: this.correlation
+    });
+  }
+  verbose(message, metadata) {
+    this.log(message, 'verbose', metadata);
+  }
+  debug(message, metadata) {
+    this.log(message, 'debug', metadata);
+  }
+  info(message, metadata) {
+    this.log(message, 'info', metadata);
+  }
+  warning(message, metadata) {
+    this.log(message, 'warning', metadata);
+  }
+  error(message, metadata) {
+    this.log(message, 'error', metadata);
+  }
+  todo(message, metadata) {
+    this.log(message, 'todo', metadata);
+  }
+
+  /** Child scope: inherits this scope's subsystem unless overridden, merges
+   * metadata (child keys win). The merge happens at construction, like any
+   * scope snapshot — both sides are materialized here so later mutation of
+   * the caller's object cannot change what the child reports. */
+  scoped(correlation, subsystem, metadata) {
+    const child = safeSnapshotMetadata(metadata);
+    const merged = this.metadata ? Object.assign(Object.create(null), this.metadata, child) : child;
+    return new ScopedLogger(this.logger, correlation, subsystem ?? this.subsystem, merged);
+  }
+}
+//# sourceMappingURL=ScopedLogger.js.map

package/lib/module/ScopedLogger.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["safeSnapshotMetadata","ScopedLogger","constructor","logger","correlation","subsystem","metadata","snapshot","Object","freeze","undefined","log","message","level","logMessage","scopeMetadata","verbose","debug","info","warning","error","todo","scoped","child","merged","assign","create"],"sourceRoot":"../../src","sources":["ScopedLogger.ts"],"mappings":";;AAEA,SAASA,oBAAoB,QAAQ,eAAY;;AAEjD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,YAAY,CAAC;EACxB;AACF;AACA;;EAGEC,WAAWA,CACQC,MAAc,EACtBC,WAAmB,EACnBC,SAAkB,EAC3BC,QAAsB,EACtB;IAAA,KAJiBH,MAAc,GAAdA,MAAc;IAAA,KACtBC,WAAmB,GAAnBA,WAAmB;IAAA,KACnBC,SAAkB,GAAlBA,SAAkB;IAG3B,MAAME,QAAQ,GAAGP,oBAAoB,CAACM,QAAQ,CAAC;IAC/C,IAAI,CAACA,QAAQ,GAAGC,QAAQ,GAAGC,MAAM,CAACC,MAAM,CAACF,QAAQ,CAAC,GAAGG,SAAS;EAChE;EAEAC,GAAGA,CACDC,OAAoB,EACpBC,KAAe,GAAG,MAAM,EACxBP,QAAsB,EAChB;IACN,IAAI,CAACH,MAAM,CAACW,UAAU,CAACF,OAAO,EAAE;MAC9BC,KAAK;MACLR,SAAS,EAAE,IAAI,CAACA,SAAS;MACzB;MACA;MACA;MACA;MACAU,aAAa,EAAE,IAAI,CAACT,QAAQ;MAC5BA,QAAQ;MACRF,WAAW,EAAE,IAAI,CAACA;IACpB,CAAC,CAAC;EACJ;EAEAY,OAAOA,CAACJ,OAAoB,EAAEN,QAAsB,EAAQ;IAC1D,IAAI,CAACK,GAAG,CAACC,OAAO,EAAE,SAAS,EAAEN,QAAQ,CAAC;EACxC;EAEAW,KAAKA,CAACL,OAAoB,EAAEN,QAAsB,EAAQ;IACxD,IAAI,CAACK,GAAG,CAACC,OAAO,EAAE,OAAO,EAAEN,QAAQ,CAAC;EACtC;EAEAY,IAAIA,CAACN,OAAoB,EAAEN,QAAsB,EAAQ;IACvD,IAAI,CAACK,GAAG,CAACC,OAAO,EAAE,MAAM,EAAEN,QAAQ,CAAC;EACrC;EAEAa,OAAOA,CAACP,OAAoB,EAAEN,QAAsB,EAAQ;IAC1D,IAAI,CAACK,GAAG,CAACC,OAAO,EAAE,SAAS,EAAEN,QAAQ,CAAC;EACxC;EAEAc,KAAKA,CAACR,OAAoB,EAAEN,QAAsB,EAAQ;IACxD,IAAI,CAACK,GAAG,CAACC,OAAO,EAAE,OAAO,EAAEN,QAAQ,CAAC;EACtC;EAEAe,IAAIA,CAACT,OAAoB,EAAEN,QAAsB,EAAQ;IACvD,IAAI,CAACK,GAAG,CAACC,OAAO,EAAE,MAAM,EAAEN,QAAQ,CAAC;EACrC;;EAEA;AACF;AACA;AACA;EACEgB,MAAMA,CACJlB,WAAmB,EACnBC,SAAkB,EAClBC,QAAsB,EACR;IACd,MAAMiB,KAAK,GAAGvB,oBAAoB,CAACM,QAAQ,CAAC;IAC5C,MAAMkB,MAAM,GAAG,IAAI,CAAClB,QAAQ,GACxBE,MAAM,CAACiB,MAAM,CAACjB,MAAM,CAACkB,MAAM,CAAC,IAAI,CAAC,EAAiB,IAAI,CAACpB,QAAQ,EAAEiB,KAAK,CAAC,GACvEA,KAAK;IACT,OAAO,IAAItB,YAAY,CACrB,IAAI,CAACE,MAAM,EACXC,WAAW,EACXC,SAAS,IAAI,IAAI,CAACA,SAAS,EAC3BmB,MACF,CAAC;EACH;AACF","ignoreList":[]}

package/lib/module/config.js

@@ -0,0 +1,23 @@
+"use strict";
+
+/**
+ * Resolves the effective minimum level for a subsystem by walking the
+ * dot-separated hierarchy: exact match, then each parent (`a.b.c` → `a.b` →
+ * `a`), then undefined so the caller falls back to the global minimum.
+ * Direct port of SwiftLogger's LoggerConfiguration.resolveSubsystemLevel.
+ *
+ * Single-threaded JS means no snapshot/locking machinery — a plain Map
+ * mutated by the fluent config methods is safe.
+ */
+export function resolveSubsystemLevel(subsystemLevels, name) {
+  if (subsystemLevels.size === 0) return undefined;
+  let current = name;
+  for (;;) {
+    const level = subsystemLevels.get(current);
+    if (level !== undefined) return level;
+    const dot = current.lastIndexOf('.');
+    if (dot < 0) return undefined;
+    current = current.slice(0, dot);
+  }
+}
+//# sourceMappingURL=config.js.map

package/lib/module/config.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["resolveSubsystemLevel","subsystemLevels","name","size","undefined","current","level","get","dot","lastIndexOf","slice"],"sourceRoot":"../../src","sources":["config.ts"],"mappings":";;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASA,qBAAqBA,CACnCC,eAA8C,EAC9CC,IAAY,EACU;EACtB,IAAID,eAAe,CAACE,IAAI,KAAK,CAAC,EAAE,OAAOC,SAAS;EAChD,IAAIC,OAAO,GAAGH,IAAI;EAClB,SAAS;IACP,MAAMI,KAAK,GAAGL,eAAe,CAACM,GAAG,CAACF,OAAO,CAAC;IAC1C,IAAIC,KAAK,KAAKF,SAAS,EAAE,OAAOE,KAAK;IACrC,MAAME,GAAG,GAAGH,OAAO,CAACI,WAAW,CAAC,GAAG,CAAC;IACpC,IAAID,GAAG,GAAG,CAAC,EAAE,OAAOJ,SAAS;IAC7BC,OAAO,GAAGA,OAAO,CAACK,KAAK,CAAC,CAAC,EAAEF,GAAG,CAAC;EACjC;AACF","ignoreList":[]}