NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
pub.dev
pub.dev, #1037 most downloaded on pub.dev
Simplifies manual JSON parsing with a type-safe API. No dynamic, no manual casting. Flexible inputs types, fixed output types. Useful parsing error messages
Latest stable
1.3.0
Last release 1 months ago
13 Oct 2026
Release timing varies
gaps range from 2 weeks to 2.1 years
Nearly every release is documented
notes for 20 of 20 stable releases
Nothing withdrawn
no release was ever pulled
7 years old
23 releases · first in 2019
Drag across the ruler to compare, or tap a release to open it.
New mapValue for asMap*() and asJsonObject*() parses the values of a map, like the mapper of asList* does for the items of a list #73. An error inside
New mapValue for asMap*() and asJsonObject*() parses the values of a map, like the mapper of asList* does for the items of a list #73.
An error inside a value reports the full location, like adidas.id.
// {"nike": {"id": "421"}, "adidas": {"id": "532"}}
Map<String, Shoe> shoes = pick(json).asJsonObjectOrEmpty(mapValue: Shoe.fromPick);
New whenNullValue maps the entries with a null value, which mapValue ignores, like whenNull does for lists.
Map<String, Shoe?> shoes = pick(json).asJsonObjectOrEmpty(
mapValue: Shoe.fromPick,
whenNullValue: (pick) => null,
);
New mapKey converts the keys.
It receives a pick of the key, so the usual parsers work on it.
// {"421": {"name": "Nike Zoom Fly 3"}}
Map<int, Shoe> shoes = pick(json).asMapOrEmpty(
mapKey: (key) => key.asIntOrThrow(),
mapValue: Shoe.fromPick,
);
The keys of asJsonObject*() stay Strings, its mapKey can rename them.
Use asMap*() to convert the keys to another type.
All six parsers are affected: asMapOrThrow(), asMapOrEmpty(), asMapOrNull(), asJsonObjectOrThrow(), asJsonObjectOrEmpty() and asJsonObjectOrNull().
asJsonObject*() got two type parameters for it, a call without arguments still returns a Map<String, Object?>.
New asPlainListOrThrow(), asPlainListOrEmpty() and asPlainListOrNull() return the items of a List as they are, without a mapper #74.
Declare the item type to get a typed list, an item of another type throws a PickException that names it.
List<Object?> items = pick(json, 'tags').asPlainListOrEmpty();
List<String> tags = pick(json, 'tags').asPlainListOrEmpty();
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Deprecated Pick.path, Pick.missingValueAtIndex, Pick.followablePath and Pick.debugParsingExit. The error message of a PickException shows where a pick…
Better error messages #64, especially for absent values
PickException: expected a non-null value at shoes[0].name, but it is absent
query shoes[0].name
~~~~ no such key
at shoes[0] = {"id": 42, "size": "M"}
hint Use asStringOrNull() when the value may be null/absent at some point (String?).
A value that can't be parsed is shown with its type, and large values are shortened.
PickException: could not parse an int at shoes[0].size
query shoes[0].size
found "M" (a String)
New asJsonObjectOrThrow(), asJsonObjectOrEmpty() and asJsonObjectOrNull() return a Map<String, Object?> that goes straight into a fromJson function, no type arguments needed #70.
Entries with a key that isn't a String are ignored.
New asJsonObjectListOrThrow(), asJsonObjectListOrEmpty() and asJsonObjectListOrNull() for a list of JSON objects #70.
// before
pick(json, 'users').asListOrEmpty((pick) => pick.asMapOrThrow<String, dynamic>());
// after
pick(json, 'users').asJsonObjectListOrEmpty();
New asMapListOrThrow<K, V>(), asMapListOrEmpty<K, V>() and asMapListOrNull<K, V>() for a list of maps with any key type #70.
Fix Pick.isAbsent is true below a null, however the path is written #64.
pick({'a': null}, 'a', 'b').isAbsent was false, while pick({'a': null}, 'a')('b').isAbsent was true.
New PickException.fromPick(pick, 'expected a Timestamp') lets custom parsers throw errors like the built-in ones #64.
New Pick.redactValues() masks error values while keeping keys and types visible; Pick.redactsValues exposes the policy to custom parsers and RequiredPick.redactValues() preserves non-null chaining #65.
Fix as*OrThrow() and letOrThrow() no longer leave an internal _required_pick_error_hint entry in Pick.context.
That also makes them as fast as their OrNull counterparts #68.
Deprecated Pick.path, Pick.missingValueAtIndex, Pick.followablePath and Pick.debugParsingExit.
The error message of a PickException shows where a pick failed.
A custom parser that built its message from them throws PickException.fromPick(this, 'expected a Foo') instead #69.
Allow .letOrNull((pick) => null) to return null without manually setting a nullable type #61
.letOrNull((pick) => null) to return null without manually setting a nullable type #61` BREAKING CHANGES ├─┬ Class Pick │ └── Field "addContext" removed (CF01) ├─┬ Class RequiredPick │ └── Field "addContext" removed (CF01) ├─┬ Class Boo…
addContext, asBool, asDateTime, asDouble, asInt, asList, asMap, asString. Use their as*OrThrow replacements.asDateTime* methods #47, #51RFC 3339, RFC 2822 and RFC 1036BREAKING CHANGES
├─┬ Class Pick
│ └── Field "addContext" removed (CF01)
├─┬ Class RequiredPick
│ └── Field "addContext" removed (CF01)
├─┬ Class BoolPick
│ └── Field "asBool" removed (CF01)
├─┬ Class NullableDateTimePick
│ └── Field "asDateTime" removed (CF01)
├─┬ Class NullableDoublePick
│ └── Field "asDouble" removed (CF01)
├─┬ Class NullableIntPick
│ └── Field "asInt" removed (CF01)
├─┬ Class NullableListPick
│ └── Method "asList" removed (CE10)
├─┬ Class NullableMapPick
│ └── Field "asMap" removed (CF01)
└─┬ Class NullableStringPick
└── Field "asString" removed (CF01)
New: Support for more date formats. asDateTime* received an optional format parameter. By default, all possible formats will be parsed. To the existin
asDateTime* received an optional format parameter. By default, all possible formats will be parsed. To the existing ISO 8601 format, RFC 1123, RFC 850 and asctime have been added which are typically used for the HTTP header or cookies.asDouble and asMapNew: pickFromJson(json, args...) allows parsing of a json String, without manually calling jsonDecode #41
New: pickFromJson(json, args...) allows parsing of a json String, without manually calling jsonDecode #41
New: pickDeep(json, 'some.key.inside.the.object'.split('.')) allows picking with a dynamic depth #40
Add Pick.index to get the element index for list items #38
pick(["John", "Paul", "George", "Ringo"]).asListOrThrow((pick) {
final index = pick.index!;
return Artist(id: index, name: pick.asStringOrThrow());
);
Pick.asIntOrThrow() now allows parsing of doubles when one of the new roundDouble or truncateDouble parameters is true #37. Thx @stevendz
Add dartdoc to asList*() extensions
Deprecated parsing extensions of RequiredPick to acknowledge that all parsers eventually causes errors. From now on, always use .asIntOrThrow() instea…
RequiredPick to acknowledge that all parsers eventually causes errors.
From now on, always use .asIntOrThrow() instead of .required().asInt(). Only exception is .required().toString().
Read more in #34dynamic with Object where possiblePick.location() to Pick.debugParsingExitPickLocaiton and PickContext mixins. They are now part of PickRequiredPick now extends Pick making it easier to write parsers for custom typesThis release is available as backport for Dart <2.12 with version 0.6.10
Enable nullsafety (requires Dart >=2.12)
Enable nullsafety (requires Dart >=2.12)
Backports 0.8.0 to pre-nullsafety
Backports 0.8.0 to pre-nullsafety
Remove long deprecated parseJsonTo* methods. Use the pick(json, args*) api
Remove long deprecated parseJsonTo* methods. Use the pick(json, args*) api
New asXyzOrThrow() methods as shorthand for .required().asXyz() featuring better error messages
asBoolOrThrow()asDateTimeOrThrow()asDoubleOrThrow()asIntOrThrow()letOrThrow()asListOrThrow()asMapOrThrow()asStringOrThrow()New Pick.isAbsent getter to check if a value is absent or null #24. Absent could mean
MapList when the index is greater than the lengthMap but the found data a Object which isn't a MapNew RequiredPick.nullable() converting a RequiredPick back to a Pick with potential null value
New PickLocation.followablePath. While PickLocation.path contains the full path to the value, followablePath contains only the part which could be followed with a non-nullable value
Breaking asList*() now requires the mapping function.
Breaking asList*() now ignores null values when parsing. The map function now receives a RequiredPick as fist parameter instead of a Pick with a potential null value, making parsing easier.
Therefore pick().required().asList((RequiredPick pick) => /*...*/) only maps non-nullable values. When your lists contain null it will be ignored.
This is fine in most cases and simplifies the map function.
In rare cases, where your lists contain null values with meaning, use the second parameter whenNull to map those null values .asList((pick) => Person.fromPick(pick), whenNull: (Pick it) => null). The function still receives a Pick which gives access to the context api or the PickLocation. But the Pick never holds any value.
Breaking asList*() methods now ignore null values. The map function now receives a RequiredPick as fist parameter instead of a Pick making parsing eas
Breaking asList*() methods now ignore null values. The map function now receives a RequiredPick as fist parameter instead of a Pick making parsing easier.
Therefore pick().required().asList((RequiredPick pick) => /*...*/) only maps non-nullable values. When your lists contain null it will be ignored.
This is fine in most cases and simplifies the map function.
In rare cases, where your lists contain null values with meaning, use the second parameter whenNull to map those null values .asList((pick) => Person.fromPick(pick), whenNull: (Pick it) => null). The function still receives a Pick which gives access to the context api or the PickLocation. But the Pick never holds any value.
Breaking Don't parse doubles as int because the is no rounding method which satisfies all #31
Breaking Allow parsing of "german" doubles with , as decimal separator #30
Improve error messages with more details where parsing stopped
New RequiredPick.nullable() converting a RequiredPick back to a Pick with potential null value
New PickLocation.followablePath. While PickLocation.path contains the full path to the value, followablePath contains only the part which could be followed with a non-nullable value
New asXyzOrThrow() methods as shorthand for .required().asXyz() featuring better error messages
asXyzOrThrow() methods as shorthand for .required().asXyz() featuring better error messages
asBoolOrThrow()asDateTimeOrThrow()asDoubleOrThrow()asIntOrThrow()letOrThrow()asListOrThrow()asMapOrThrow()asStringOrThrow()Pick.isAbsent getter to check if a value is absent or null #24. Absent could mean
MapList when the index is greater than the lengthMap but the found data a Object which isn't a Map"true" and "false" are now parsed as booleanRemove deprecated long deprecated parseJsonTo* methods. Use the pick(json, args*) api
parseJsonTo* methods. Use the pick(json, args*) apiparseJsonTo* methods. Use the pick(json, args*) apiRename Pick.addContext to Pick.withContext using deprecation
Pick.addContext to Pick.withContext using deprecationPick.fromContext now accepts 10 arguments for nested structuresPick.fromContext always returning context not the value for key in context MapNew context API. You can now attach relevant additional information for parsing directly to the Pick object. This allows passing information into from
Pick object. This allows passing information into fromPick constructors without adding new parameters to all constructors in between.// Add context
final shoes = pick(json, 'shoes')
.addContext('apiVersion', "2.3.0")
.addContext('lang', "en-US")
.asListOrEmpty((p) => Shoe.fromPick(p.required()));
import 'package:version/version.dart';
// Read context
factory Shoe.fromPick(RequiredPick pick) {
// read context API
final version = pick.fromContext('newApi').required().let((pick) => Version(pick.asString()));
return Shoe(
id: pick('id').required().asString(),
name: pick('name').required().asString(),
// manufacturer is a required field in the new API
manufacturer: version >= Version(2, 3, 0)
? pick('manufacturer').required().asString()
: pick('manufacturer').asStringOrNull(),
tags: pick('tags').asListOrEmpty(),
);
}
Pick and RequiredPick have chained their constructor signature. path is now a named argument
and context has been added.- RequiredPick(this.value, [this.path = const []])
+ RequiredPick(this.value, {this.path = const [], Map<String, dynamic> context})
path is now correctly forwarded after Pick#call or Pick#asListOrEmpty and always shows the full path since originFix error reporting for asMapOr[Empty|Null] and don't swallow parsing errors
asMapOr[Empty|Null] and don't swallow parsing errorsFix error reporting of asListOrNull(mapToUser) and asListOrEmpty(mapToUser). Both now return errors during mapping and don't swallow them
asListOrNull(mapToUser) and asListOrEmpty(mapToUser). Both now return errors during mapping and don't swallow themPrint correct path in error message when json is null
nullasDateTime() now skips parsing when the value is already a DateTimeNote: Calling .asString() directly on Pick has been deprecated. You now have to call required() first to convert the Pick to a RequiredPick or use a m…
New APIs to map picks to objects and to map list elements to obejcts.
RequiredPick.let<R>(R Function(RequiredPick pick) block): R
Pick.letOrNull<R>(R Function(RequiredPick pick) block): R
RequiredPick.asList<T>([T Function(Pick) map]): List<T>
Pick.asListOrNull<T>([T Function(Pick) map]): List<T>
Pick.asListOrEmpty<T>([T Function(Pick) map]): List<T>
Here are two example how to actually use them.
// easily pick and map objects to dart objects
final Shoe oneShoe = pick(json, 'shoes', 0).letOrNull((p) => Shoe.fromPick(p));
// map list of picks to dart objects
final List<Shoe> shoes =
pick(json, 'shoes').asListOrEmpty((p) => Shoe.fromPick(p.required()));
Pick now offers a new required() method returning a RequiredPick. It makes sure the picked value exists or crashes if it is null. Because it can't be null, RequiredPick doesn't offer fallback methods like .asIntOrNull() but only .asInt(). This makes the API a bit easier to use for values you can't live without.
// use required() to crash if a object doesn't exist
final name = pick(json, 'shoes', 0, 'name').required().asString();
print(name); // Nike Zoom Fly 3
Note: Calling .asString() directly on Pick has been deprecated. You now have to call required() first to convert the Pick to a RequiredPick or use a mapping method with fallbacks.
Ever got a Pick/RequiredPick and you wanted to pick even further. This is now possible with the call method. Very useful in constructors when parsing methods.
factory Shoe.fromPick(RequiredPick pick) {
return Shoe(
id: pick('id').required().asString(),
name: pick('name').required().asString(),
manufacturer: pick('manufacturer').asStringOrNull(),
tags: pick('tags').asListOrEmpty(),
);
}
List.asMap(), .asMapOrNull() and .asMapOrEmpty() now consistently return Map<dynamic, dynamic> (was Map<String, dynamic>)Also the lib has been converted to use static extension methods which were introduced in Dart 2.6
asMap now expects the key type, defaults to dynamic instead of String
asMap now expects the key type, defaults to dynamic instead of String
-Pick.asMap(): Map<String, dynamic>
+Pick.asMap<T>(): Map<T, dynamic>
New API! The old parse* methods are now deprecated, but still work. Replace them with the new pick(json, arg0-9...) method.
New API!
The old parse* methods are now deprecated, but still work.
Replace them with the new pick(json, arg0-9...) method.
- final name = parseJsonToString(json, 'shoes', 0, 'name');
+ final name = pick(json, 'shoes', 0, 'name').asString();
pick returns a Pick which offers a rich API to parse values.
.asString()
.asStringOrNull()
.asMap()
.asMapOrEmpty()
.asMapOrNull()
.asList()
.asListOrEmpty()
.asListOrNull()
.asBool()
.asBoolOrNull()
.asBoolOrTrue()
.asBoolOrFalse()
.asInt()
.asIntOrNull()
.asDouble()
.asDoubleOrNull()
.asDateTime()
.asDateTimeOrNull()
- pubspec description updated
- Initial version
One column per quarter.