JsonSentinel class

Lightweight runtime JSON key and type validation with a configurable logger.

Validates a Map<String, dynamic> against an expected schema — checking key existence and value types — without code generation. Designed for use in tryFromJson methods to catch malformed API responses early.

All methods are static; this class cannot be instantiated.

The fallback logger (used when neither configure nor silence has been called) writes to dart:developer and is suppressed in release builds — always call configure or silence in production code.

Pass verbose: true to either configure or silence 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. Verbose output is orthogonal to silence.

Quick start

// 1. Wire in your logger once at startup:
JsonSentinel.configure((message, {error, stackTrace, extras, escalate}) {
  myLogger.warn(message, stackTrace: stackTrace, extras: extras, escalate: escalate ?? false);
});

// 2. Validate in tryFromJson:
final result = JsonSentinel.validate(
  json: responseJson,
  expectedTypes: {
    'productId': [int],
    'sku':       [String],
    'price':     [int, double],
    'description': [String, null], // nullable
  },
  optional: {'description'}, // present-or-absent is fine
  context: 'ProductListing',
);
if (!result.isValid) return null;