{"id":13549318,"url":"https://github.com/simc/crimson","last_synced_at":"2025-04-10T00:19:20.273Z","repository":{"id":144684075,"uuid":"582650069","full_name":"simc/crimson","owner":"simc","description":"Fast, efficient and easy-to-use JSON parser and serializer for Dart.","archived":false,"fork":false,"pushed_at":"2024-04-02T15:56:00.000Z","size":3610,"stargazers_count":232,"open_issues_count":10,"forks_count":7,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-10-19T11:09:34.164Z","etag":null,"topics":["dart","flutter","json","parser","serializer"],"latest_commit_sha":null,"homepage":"","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-12-27T13:26:32.000Z","updated_at":"2024-09-12T19:55:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"d6243fbb-affd-4770-ac83-ea0ba4de372f","html_url":"https://github.com/simc/crimson","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simc%2Fcrimson","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simc%2Fcrimson/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simc%2Fcrimson/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simc%2Fcrimson/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simc","download_url":"https://codeload.github.com/simc/crimson/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248131492,"owners_count":21052857,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dart","flutter","json","parser","serializer"],"created_at":"2024-08-01T12:01:20.621Z","updated_at":"2025-04-10T00:19:20.251Z","avatar_url":"https://github.com/simc.png","language":"Dart","funding_links":[],"categories":["Dart"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003ca href=\"https://github.com/simc/crimson\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/simc/crimson/main/.github/crimson.svg\" width=\"350\"\u003e\n  \u003c/a\u003e\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pub.dev/packages/crimson\"\u003e\n    \u003cimg src=\"https://img.shields.io/pub/v/crimson?label=pub.dev\u0026labelColor=333940\u0026logo=dart\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/simc/crimson/actions/workflows/test.yaml\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/actions/workflow/status/simc/crimson/test.yaml?branch=main\u0026label=tests\u0026labelColor=333940\u0026logo=github\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://app.codecov.io/gh/simc/crimson\"\u003e\n    \u003cimg src=\"https://img.shields.io/codecov/c/github/simc/crimson?logo=codecov\u0026logoColor=fff\u0026labelColor=333940\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://twitter.com/simcdev\"\u003e\n    \u003cimg src=\"https://img.shields.io/twitter/follow/simcdev?style=flat\u0026label=Follow\u0026color=1DA1F2\u0026labelColor=333940\u0026logo=twitter\u0026logoColor=fff\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003eFast, efficient and easy-to-use JSON parser and serializer for Dart.\u003cbr\u003eCrimson does not verify your JSON!\u003c/p\u003e\n\n## Features\n\n- 🏎️ **Fast**: Like really fast. Crimson parses JSON in a single pass.\n- 🌻 **Easy to use**: Crimson is designed to be easy to learn and use.\n- 💃 **Flexible**: Crimson can partially parse and serialize JSON.\n- 🥶 **Freezed support**: Crimson supports [freezed](https://pub.dev/packages/freezed) classes.\n- 🪶 **Lightweight**: Crimson is lightweight and has no third-party dependencies.\n\n## Usage\n\nAfter adding Crimson to your `pubspec.yaml`, you can start annotating your classes with `@json` and optionally `@JsonField()`:\n\n```dart\nimport 'package:crimson/crimson.dart';\n\npart 'tweet.g.dart';\n\n@json\nclass Tweet {\n  DateTime? createdAt;\n\n  String? tweet;\n\n  int? favoriteCount;\n}\n```\n\nNow you just need to run `pub run build_runner build` to generate the necessary code.\n\n```dart\nimport 'package:crimson/crimson.dart';\n\nvoid main() {\n  final jsonBytes = downloadTweets();\n\n  final crimson = Crimson(jsonBytes);\n  final tweets = crimson.readTweetList();\n\n  final writer = CrimsonWriter();\n  writer.writeTweetList(tweets);\n  final bytes = writer.toBytes();\n}\n```\n\nThat's it! You can now parse and serialize JSON with ease.\n\n## Ignoring JSON fields\n\nAnnotate properties with `@jsonIgnore` to ignore them:\n\n```dart\n@json\nclass Tweet {\n  DateTime? created_at;\n\n  String? tweet;\n\n  @jsonIgnore\n  int? favoriteCount;\n}\n```\n\n## Renaming JSON fields\n\nUse the `@JsonName()` annotation to rename individual fields:\n\n```dart\n@json\nclass Tweet {\n  @JsonName('created_at')\n  DateTime? createdAt;\n\n  @JsonName('text', aliases: {'alias1', 'alias2'})\n  String? tweet;\n}\n```\n\nThe same works for enum values:\n\n```dart\n@json\nenum TweetType {\n  tweet,\n\n  @JsonName('re-tweet')\n  retweet,\n}\n```\n\nIf you want to rename all fields or enum values, you can use `@jsonKebabCase` and `@jsonSnakeCase`:\n\n```dart\n@jsonKebabCase\nclass Tweet {\n  DateTime? createdAt; // created-at\n\n  String? tweet; // tweet\n\n  int? favoriteCount; // favorite-count\n}\n\n@jsonSnakeCase\nenum PlaceType {\n  country, // country\n  largeCity, // large_city\n  smallCity, // small_city\n}\n```\n\n## fromJson and toJson methods\n\nCrimson supports generating a `fromJson()` constructor and a `toJson()` extension method for your classes use `Uint8List`.\n\nJust add the following line to your class. The `.toJson()` method is generated using an extension.\n\n```dart\n@json\nclass Tweet {\n  // ...\n\n  factory Tweet.fromJson(Uint8List json) =\u003e _$TweetFromJson(json);\n}\n```\n\nAlternatively you can use `fromBytes()` and `toBytes()`. It's equivalent to `fromJson()` and `toJson()`.\n\n```dart\n@json\nclass Tweet {\n  // ...\n\n  factory Tweet.fromBytes(Uint8List bytes) =\u003e _$TweetFromBytes(bytes);\n}\n```\n\n## JSON Pointers\n\nCrimson supports [RFC 6901 JSON pointers](https://www.rfc-editor.org/rfc/rfc6901) to access nested JSON fields:\n\n```json\n{\n  \"user\": {\n    \"name\": \"Simon Choi\"\n  },\n  \"tweets\": [\n    {\n      \"text\": \"Hello World!\"\n    },\n    {\n      \"text\": \"Hello Crimson!\"\n    }\n  ]\n}\n```\n\nWe can access the `name` field of the `user` object and the `text` field of the second tweet by providing a JSON pointer:\n\n```dart\n@json\nclass Tweet {\n  @JsonName('/user/name')\n  String? userName;\n\n  @JsonName('/tweets/1/text')\n  String? secondTweet;\n}\n```\n\nJSON pointers are evaluated at compile time and optimized code is generated so there is no runtime overhead.\n\nFields using JSON pointers are ignored for serialization.\n\n**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.\n\n## Custom JSON converters\n\nYou can use custom JSON converters to convert between JSON and Dart types using the `@JsonConvert()` annotation:\n\n```dart\n@json\nclass Tweet {\n  String? tweet;\n\n  @JsonConvert(fromJson: jsonIntToBool, toJson: boolToJsonInt)\n  bool? isFavorite;\n}\n\nbool jsonIntToBool(int json) =\u003e json \u003e= 1;\n\nint boolToJsonInt(bool value) =\u003e value ? 1 : 0;\n```\n\n## Freezed Support\n\nCrimson supports classes annotated with `@freezed` from the [freezed](https://pub.dev/packages/freezed) package.\n\n```dart\nimport 'package:crimson/crimson.dart';\n\npart 'tweet.g.dart';\npart 'tweet.freezed.dart';\n\n@freezed\nclass Tweet with _$Tweet {\n  @json\n  const factory Tweet({\n    DateTime? created_at,\n    @JsonField(name: 'text') String? tweet,\n    int? reply_count,\n    int? retweet_count,\n    int? favorite_count,\n  }) = _Tweet;\n}\n```\n\n## JSON Benchmarks\n\nThe 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.\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cpicture\u003e\n        \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/simc/crimson/main/.github/benchmarks/big_json_dark.png\"\u003e\n        \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://raw.githubusercontent.com/simc/crimson/main/.github/benchmarks/big_json_light.png\"\u003e\n        \u003cimg src=\"https://raw.githubusercontent.com/simc/crimson/main/.github/benchmarks/big_json_light.png\"\u003e\n      \u003c/picture\u003e\n      \u003cb\u003eBig JSON without whitespace\u003c/b\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cpicture\u003e\n        \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/simc/crimson/main/.github/benchmarks/big_json_whitespace_dark.png\"\u003e\n        \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://raw.githubusercontent.com/simc/crimson/main/.github/benchmarks/big_json_whitespace_light.png\"\u003e\n        \u003cimg src=\"https://raw.githubusercontent.com/simc/crimson/main/.github/benchmarks/big_json_whitespace_light.png\"\u003e\n      \u003c/picture\u003e\n      \u003cb\u003eBig JSON with whitespace\u003c/b\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cpicture\u003e\n        \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/simc/crimson/main/.github/benchmarks/medium_json_dark.png\"\u003e\n        \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://raw.githubusercontent.com/simc/crimson/main/.github/benchmarks/medium_json_light.png\"\u003e\n        \u003cimg src=\"https://raw.githubusercontent.com/simc/crimson/main/.github/benchmarks/medium_json_light.png\"\u003e\n      \u003c/picture\u003e\n      \u003cb\u003eMedium JSON without whitespace\u003c/b\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cpicture\u003e\n        \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/simc/crimson/main/.github/benchmarks/small_json_dark.png\"\u003e\n        \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://raw.githubusercontent.com/simc/crimson/main/.github/benchmarks/small_json_light.png\"\u003e\n        \u003cimg src=\"https://raw.githubusercontent.com/simc/crimson/main/.github/benchmarks/small_json_light.png\"\u003e\n      \u003c/picture\u003e\n      \u003cb\u003eSmall JSON without whitespace\u003c/b\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n### License\n\n```\nCopyright 2023 Simon Choi\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n   http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimc%2Fcrimson","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimc%2Fcrimson","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimc%2Fcrimson/lists"}