configure static method

void configure(
  1. JsonLogFn logFn, {
  2. bool verbose = false,
  3. Set<String>? redactKeys,
  4. String redactionPlaceholder = '[REDACTED]',
})

Configures the logger used for all validation failures.

Call once at app startup as an alternative to silence — never both. Asserts in debug mode if called after configure or silence has already been called. In release mode the second call is silently ignored — the first registration wins. Tests should call resetLoggerForTesting in tearDown to allow re-configuration across test cases.

Set verbose to true to enable trace-level dart:developer logs: a confirmation on initialisation, a success trace on every passing validate call, and a diagnostic when jsonEncode fails in the JSON preview. Verbose output is independent of silence — the two are orthogonal controls.

Pass redactKeys to mask sensitive top-level field values in json_preview and item_previews extras before they are forwarded to the logger. Any key present in redactKeys has its value replaced with redactionPlaceholder (defaults to '[REDACTED]') in the preview string — the validated data itself is never modified. Keys absent from redactKeys appear in previews unchanged.

Implementation

static void configure(
  JsonLogFn logFn, {
  bool verbose = false,
  Set<String>? redactKeys,
  String redactionPlaceholder = '[REDACTED]',
}) {
  assert(
    _logger == null,
    'JsonSentinel is already initialised — configure() or silence() has already been called. '
    'Call JsonSentinel.resetLoggerForTesting() in tearDown if overriding in tests.',
  );
  if (_logger != null) return;
  _verbose = verbose;
  _logger = logFn;
  _redactKeys = redactKeys;
  _redactionPlaceholder = redactionPlaceholder;
  if (_verbose) developer.log('Logger configured.', name: 'JsonSentinel');
}