crimson 0.1.2 crimson: ^0.1.2 copied to clipboard
Fast, efficient and easy-to-use JSON parser and serializer for Dart.
Fast, efficient and easy-to-use JSON parser and serializer for Dart.
Crimson does not verify your JSON!
ð§ Crimson is still in early development and is not ready for production use.
Only parsing is supported for now ð§
Features #
- ðïļ Fast: Like really fast. Crimson parses JSON in a single pass.
- ðŧ Easy to use: Crimson is designed to be easy to learn and use.
- ð Flexible: Crimson can partially parse and serialize JSON.
- ðĨķ Freezed support: Crimson supports freezed classes.
- ðŠķ Lightweight: Crimson is lightweight and has no third-party dependencies.
Usage #
After adding Crimson to your pubspec.yaml
, you can start annotating your classes with @json
and optionally @JsonField()
:
import 'package:crimson/crimson.dart';
part 'tweet.g.dart';
@json
class Tweet {
DateTime? createdAt;
String? tweet;
int? favoriteCount;
}
Now you just need to run pub run build_runner build
to generate the necessary code.
import 'package:crimson/crimson.dart';
void main() {
final jsonBytes = downloadTweets();
final crimson = Crimson(jsonBytes);
final tweets = crimson.parseTweetList();
}
That's it! You can now parse and serialize JSON with ease.
Ignoring JSON fields #
Annotate properties with @jsonIgnore
to ignore them:
@json
class Tweet {
DateTime? created_at;
String? tweet;
@jsonIgnore
int? favoriteCount;
}
Renaming JSON fields #
Use the @JsonName()
annotation to rename individual fields:
@json
class Tweet {
@JsonName('created_at')
DateTime? createdAt;
@JsonName('text', aliases: {'alias1', 'alias2'})
String? tweet;
}
The same works for enum values:
@json
enum TweetType {
tweet,
@JsonName('re-tweet')
retweet,
}
If you want to rename all fields or enum values, you can use @jsonKebabCase
and @jsonSnakeCase
:
@jsonKebabCase
class Tweet {
DateTime? createdAt; // created-at
String? tweet; // tweet
int? favoriteCount; // favorite-count
}
@jsonSnakeCase
enum PlaceType {
country, // country
largeCity, // large_city
smallCity, // small_city
}
Custom JSON converters #
You can use custom JSON converters to convert between JSON and Dart types using the @JsonConvert()
annotation:
@json
class Tweet {
String? tweet;
@JsonConvert(fromJson: jsonIntToBool, toJson: boolToJsonInt)
bool? isFavorite;
}
bool jsonIntToBool(int json) => json >= 1;
int boolToJsonInt(bool value) => value ? 1 : 0;
Freezed Support #
Crimson supports classes annotated with @freezed
from the freezed package.
import 'package:crimson/crimson.dart';
part 'tweet.g.dart';
part 'tweet.freezed.dart';
@freezed
class Tweet with _$Tweet {
@json
const factory Tweet({
DateTime? created_at,
@JsonField(name: 'text') String? tweet,
int? reply_count,
int? retweet_count,
int? favorite_count,
}) = _Tweet;
}
JSON Benchmarks #
The following benchmarks give you an idea about the JSON parsing performance of Crimson. The benchmarks were run on a MacBook with M1 Pro and 32 GB of RAM using Twitter API data.
Big JSON without whitespace | Big JSON with whitespace |
Medium JSON without whitespace | Small JSON without whitespace |
License #
Copyright 2022 Simon Choi
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.