Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/simc/crimson
Fast, efficient and easy-to-use JSON parser and serializer for Dart.
https://github.com/simc/crimson
dart flutter json parser serializer
Last synced: 1 day ago
JSON representation
Fast, efficient and easy-to-use JSON parser and serializer for Dart.
- Host: GitHub
- URL: https://github.com/simc/crimson
- Owner: simc
- License: apache-2.0
- Created: 2022-12-27T13:26:32.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-04-02T15:56:00.000Z (9 months ago)
- Last Synced: 2024-10-19T11:09:34.164Z (2 months ago)
- Topics: dart, flutter, json, parser, serializer
- Language: Dart
- Homepage:
- Size: 3.44 MB
- Stars: 232
- Watchers: 4
- Forks: 7
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
Fast, efficient and easy-to-use JSON parser and serializer for Dart.
Crimson does not verify your JSON!
## 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](https://pub.dev/packages/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()`:
```dart
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.
```dart
import 'package:crimson/crimson.dart';
void main() {
final jsonBytes = downloadTweets();
final crimson = Crimson(jsonBytes);
final tweets = crimson.readTweetList();
final writer = CrimsonWriter();
writer.writeTweetList(tweets);
final bytes = writer.toBytes();
}
```
That's it! You can now parse and serialize JSON with ease.
## Ignoring JSON fields
Annotate properties with `@jsonIgnore` to ignore them:
```dart
@json
class Tweet {
DateTime? created_at;
String? tweet;
@jsonIgnore
int? favoriteCount;
}
```
## Renaming JSON fields
Use the `@JsonName()` annotation to rename individual fields:
```dart
@json
class Tweet {
@JsonName('created_at')
DateTime? createdAt;
@JsonName('text', aliases: {'alias1', 'alias2'})
String? tweet;
}
```
The same works for enum values:
```dart
@json
enum TweetType {
tweet,
@JsonName('re-tweet')
retweet,
}
```
If you want to rename all fields or enum values, you can use `@jsonKebabCase` and `@jsonSnakeCase`:
```dart
@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
}
```
## fromJson and toJson methods
Crimson supports generating a `fromJson()` constructor and a `toJson()` extension method for your classes use `Uint8List`.
Just add the following line to your class. The `.toJson()` method is generated using an extension.
```dart
@json
class Tweet {
// ...
factory Tweet.fromJson(Uint8List json) => _$TweetFromJson(json);
}
```
Alternatively you can use `fromBytes()` and `toBytes()`. It's equivalent to `fromJson()` and `toJson()`.
```dart
@json
class Tweet {
// ...
factory Tweet.fromBytes(Uint8List bytes) => _$TweetFromBytes(bytes);
}
```
## JSON Pointers
Crimson supports [RFC 6901 JSON pointers](https://www.rfc-editor.org/rfc/rfc6901) to access nested JSON fields:
```json
{
"user": {
"name": "Simon Choi"
},
"tweets": [
{
"text": "Hello World!"
},
{
"text": "Hello Crimson!"
}
]
}
```
We can access the `name` field of the `user` object and the `text` field of the second tweet by providing a JSON pointer:
```dart
@json
class Tweet {
@JsonName('/user/name')
String? userName;
@JsonName('/tweets/1/text')
String? secondTweet;
}
```
JSON pointers are evaluated at compile time and optimized code is generated so there is no runtime overhead.
Fields using JSON pointers are ignored for serialization.
**Important**: You can only use a pointer prefix once in a class. For example, you can't use `/user` and `/user/name` in the same class.
## Custom JSON converters
You can use custom JSON converters to convert between JSON and Dart types using the `@JsonConvert()` annotation:
```dart
@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](https://pub.dev/packages/freezed) package.
```dart
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 2023 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.
```