Json class

A safe way to read decoded JSON (from any backend: REST, Firebase, Supabase, ...) into your own models.

Reading never throws. A missing key or a value of the wrong type gives the fallback (or null for the ...OrNull readers), and is reported to Json.onProblem so you see it while developing. Values are converted when it is safe: "12" to 12, 12 to "12", "true" / 1 to true, ISO text or epoch milliseconds to DateTime.

Keys may be paths: json.string('profile.firstName').

factory User.fromJson(Json json) => User(
  id: json.string('id'),
  name: json.string('profile.firstName'),
  age: json.integer('age'),
  createdAt: json.dateOrNull('createdAt'),
  roles: json.list('roles', Role.fromJson),
);

final user = User.fromJson(Json(jsonDecode(body)));

Constructors

Json(Object? raw)
Wraps a decoded JSON value (usually a Map or a List).

Properties

hashCode → int
The hash code for this object.
no setterinherited
path → String
Where this value sits in the document, e.g. profile.roles[0]; empty for the top.
final
raw → Object?
The decoded value as it is.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

boolean(String key, [bool fallback = false]) → bool
true / false at key. Also accepts "true", "false", 1, 0.
booleanOrNull(String key) → bool?
child(String key) → Json
The object at key, for reading nested values (an empty one when it is missing).
dateOrNull(String key) → DateTime?
Date at key: ISO 8601 text or epoch milliseconds.
decimal(String key, [double fallback = 0]) → double
Number at key. Accepts 1, 1.5 and "1.5".
decimalOrNull(String key) → double?
has(String key) → bool
Whether key is present (a value, even null).
integer(String key, [int fallback = 0]) → int
Whole number at key. Accepts 12, 12.0 and "12".
integerOrNull(String key) → int?
items<T>(T parse(Json json)) → List<T>
When this value itself is a list: each item read with parse.
list<T>(String key, T parse(Json json)) → List<T>
The list at key, each item read with parse. Items that are not objects are skipped and reported. Missing to empty list.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
string(String key, [String fallback = '']) → String
Text at key. Numbers and booleans are turned into text.
stringOrNull(String key) → String?
strings(String key) → List<String>
A list of texts at key (numbers turned into text).
toString() → String
Shows the shape, not the values, a Json may hold tokens or personal data that must not reach a log.
override
value(String key) → Object?
The value at key as raw data, or null.

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Properties

onProblem ↔ void Function(String path, String problem)?
Called for every key that is missing or has a type that cannot be converted, with its path and what went wrong. null (the default) stays silent. Point it at your logger while developing: Json.onProblem = (path, problem) => log('JSON $path: $problem');
getter/setter pair