JSON Utility Kit

A minimal utility kit for working with JSON in a type-safe manner.

GitHub Actions Workflow Status

By default, Dart offers very little in the way of JSON parsing and serialization. While upcoming features like macros^1 are promising, they are not yet available (as of 2024-03-1). This package uses a (at the time of writing) new language feature, extension types to provide lightweight, type-safe JSON parsing:

import 'package:jsonut/jsonut.dart';

void main() {
  final string = '{"name": "John Doe", "age": 42}';
  final person = JsonObject.parse(string);
  print(person['name'].string()); // John Doe
  print(person['age'].number()); // 42
}

^1: Macros could be used to enhance this package once available!

Features

  • 🦺 Typesafe: JSON parsing and serialization is type-safe and easy to use.
  • 💨 Lightweight: No dependencies, code generation, or reflection.
  • 💪🏽 Flexible: Parse lazily or validate eagerly, as needed.
  • 🚫 No Bullshit: Use as little or as much as you need.

Getting Started

Simply add the package to your pubspec.yaml:

dependencies:
  jsonut: ^0.4.0

Or use the command line:

dart pub add jsonut

flutter packages add jsonut

Or, even just copy paste the code (a single .dart file) into your project:

curl -o lib/jsonut.dart https://raw.githubusercontent.com/matanlurey/jsonut/main/lib/jsonut.dart

Benchmarks

A basic decoding benchmark is included in the benchmark/ directory. To run it:

# JIT
dart run benchmark/decode.dart

# AOT
dart compile exe benchmark/decode.dart
./benchmark/decode.exe

On my machine™, a M2 MacBook Pro, there is roughly a <10% overhead compared to just using the object['...'] as ... pattern, or dynamic calls in JIT mode. In AOT mode, jsonut is faster than dynamic calls, and ~3% slower at decoding.

In short, the overhead is minimal compared to the benefits.

Contributing

The following are guidelines for contributing to this package:

  • Issues: Open an issue for any non-trivial change you'd like to make.
  • Pull Requests: Open a PR against the main branch.
  • Testing: Add tests for any new functionality or behavior changes.
  • Dependencies: Avoid adding dependencies (dev-dependencies are fine~ish).

To check code coverage locally, run:

# Generate coverage report
dart run coverage:test_with_coverage -- -P coverage

# Open coverage report if you have `genhtml` installed
genhtml coverage/lcov.info -o coverage/html && open coverage/html/index.html

Libraries

jsonut
A minimal utility kit for working with JSON in a type-safe manner.