typeson — Typed JSON values and pluggable (de)serialization for Dart

Typed wrappers for JSON values, ergonomic builders, and a flexible registry for custom (de)serialization. Works great for transforming JSON with type-safe helpers and encoding/decoding your own domain objects.

• Typed JSON nodes: JsonString, JsonNumber, JsonBoolean, JsonArray, JsonObject
• Fluent extensions: .json on primitives, lists, and maps; .build for pretty/compact output; .let for inline transforms
• Registry-based (de)serialization for custom types with pluggable parsers (envelope, flat type key, or your own)
• Raw/unsafe mode for lazy parsing and zero-copy wrapping of existing structures

Install

Add to your pubspec.yaml:

dependencies:
    tson:
        git: https://github.com/sunarya-thito/tson.git

Requires Dart SDK >= 3.0.0.

Quick start

Primitives

import 'package:typeson/tson.dart';

void main() {
  final JsonString s = 'hello'.json;
  final JsonNumber n = 42.json;
  final JsonBoolean b = true.json;

  print(s.toJson()); // "hello"
  print(n.toJson()); // 42
  print(b.toJson()); // true

  print(n.asString.value); // 42
  print('123'.json.maybeAsNumber?.value); // 123
  print('true'.json.maybeAsBoolean?.value); // true

  final JsonNumber a = 10.json;
  final JsonNumber c = 5.json;
  print((a + c).value); // 15
  print((a > c).value); // true
}

Arrays and objects

import 'package:typeson/typeson.dart';

void main() {
  // Array preserves nulls
  final JsonArray arr = [1, 'two', true, null].json;
  print(arr.toJson()); // [1,"two",true,null]

  // Object: keys stringified, null values kept in the node, but build() can drop nulls from maps (see below)
  final JsonObject obj = {
    'id': 1001,
    'name': 'Widget',
    'tags': ['a', 'b', 'c'],
    'stock': null,
  }.json;

  // Access
  print(obj['name']!.asString.value); // Widget
  print(obj['tags']!.asArray[0]!.asString.value); // a

  // Mutate
  obj['price'] = 9.99.json;
  print(obj['price']!.asNumber.doubleValue); // 9.99
}

Pretty/compact building and null elimination

The .build extension uses JsonBuilder with:

• indent: spaces per level, null for compact
• explicitNulls: when false (default), null map entries are removed; list nulls are preserved

import 'package:typeson/typeson.dart';

void main() {
  final JsonObject obj = {
    'id': 7,
    'name': 'Null Demo',
    'note': null, // removed by default
    'nested': {'keepNull': null, 'value': 1},
  }.json;

  // Default: indent=2, explicitNulls=false
  print(obj.build());
  // {
  //   "id": 7,
  //   "name": "Null Demo",
  //   "nested": {
  //     "value": 1
  //   }
  // }

  // Keep nulls
  print(obj.build(explicitNulls: true));
  // {
  //   "id": 7,
  //   "name": "Null Demo",
  //   "note": null,
  //   "nested": {
  //     "keepNull": null,
  //     "value": 1
  //   }
  // }

  // Compact
  print(obj.build(indent: null));
  // {"id":7,"name":"Null Demo","nested":{"value":1}}
}

Parse JSON string to typed nodes

import 'package:typeson/typeson.dart';

void main() {
  const raw = '{"title":"Example","count":3,"items":[{"id":1},{"id":2}]}'
      ;
  final JsonValue value = JsonValue.parse(raw);

  final JsonObject root = value.asObject;
  final title = root['title']!.asString.value;
  final count = root['count']!.asNumber.intValue;
  final firstId = root['items']!.asArray[0]!.asObject['id']!.asNumber.intValue;

  print('title=$title, count=$count, firstId=$firstId');
  // title=Example, count=3, firstId=1

  print(root.build(indent: null));
  // {"title":"Example","count":3,"items":[{"id":1},{"id":2}]}
}

Raw/unsafe mode (lazy parsing, zero-copy)

Use JsonValue.unsafe(...) or the .rawJson extension to wrap existing structures without eagerly converting elements. Booleans and numbers are parsed only when .value is accessed; lists and maps are preserved and lazily wrapped.

import 'package:typeson/typeson.dart';

void main() {
  final rawBool = JsonValue.unsafe({'ok': 'true'});
  final ok = rawBool.asObject['ok']!.asBoolean; // not parsed yet
  print(ok.value); // true

  final rawNum = JsonValue.unsafe('3.14').asNumber; // not parsed yet
  print(rawNum.value); // 3.14

  final rawList = JsonValue.unsafe([1, '2', true, null]).asArray;
  print(rawList[1]!.asNumber.intValue); // 2

  final rawMap = JsonValue.unsafe({'a': '1', 2: false}).asObject;
  print(rawMap['a']!.asNumber.value); // 1
  print(rawMap['2']!.asBoolean.value); // false

  // Mutations store raw values back
  rawMap['x'] = JsonString('hello');
  print(rawMap.toJson()); // {"a":"1","2":false,"x":"hello"}
}

Registry-based custom (de)serialization

Define entries that tell the registry how to encode/decode your types. By default, the registry uses an envelope format: {"__type": "TypeName", "__data": {...}}.

Key pieces:

• JsonRegistryEntry
• JsonRegistry: holds entries and an optional default parser
• JsonObjectParser: strategy for how objects are represented; built-ins include DefaultJsonObjectParser (envelope) and FlatTypeParser (inline with a $type key)
• JsonRegistryEntry.exactType and .assignableType helpers for matching

import 'package:typeson/typeson.dart';

class PersonName {
  final String firstName;
  final String lastName;
  PersonName(this.firstName, this.lastName);
}

class Person {
  final PersonName name;
  final int age;
  Person(this.name, this.age);
}

void main() {
  final registry = JsonRegistry(
    entries: [
      JsonRegistryEntry<PersonName>(
        type: 'PersonName',
        serializer: (e) =>
            JsonObject.wrap({'firstName': e.firstName, 'lastName': e.lastName}),
        deserializer: (json) => PersonName(
          json['firstName']!.asString.value,
          json['lastName']!.asString.value,
        ),
      ),
      JsonRegistryEntry<Person>(
        type: 'Person',
        serializer: (e) => JsonObject.wrap({
          'name': JsonRegistry.currentRegistry.serialize(e.name).asObject,
          'age': e.age,
        }),
        deserializer: (json) => Person(
          json['name']!.asType<PersonName>(),
          json['age']!.asNumber.intValue,
        ),
      ),
    ],
  );

  final input = [
    Person(PersonName('Alice', 'Smith'), 30),
    {'Bob': Person(PersonName('Bob', 'Brown'), 25)},
  ];

  final JsonValue encoded = registry.serialize(input);
  print(encoded.build());
  // [
  //   {
  //     "__type": "Person",
  //     "__data": {
  //       "name": {
  //         "__type": "PersonName",
  //         "__data": {"firstName": "Alice", "lastName": "Smith"}
  //       },
  //       "age": 30
  //     }
  //   },
  //   {
  //     "Bob": {
  //       "__type": "Person",
  //       "__data": {
  //         "name": {
  //           "__type": "PersonName",
  //           "__data": {"firstName": "Bob", "lastName": "Brown"}
  //         },
  //         "age": 25
  //       }
  //     }
  //   }
  // ]

  final decoded = registry.deserialize(encoded);
  print(decoded is List); // true
}

Flat type parser ($type discriminator)

Use FlatTypeParser to inline a type discriminator instead of the envelope:

import 'package:typeson/typeson.dart';

class Name { final String v; Name(this.v); }

void main() {
  final reg = JsonRegistry(
    parser: const FlatTypeParser(), // defaults to discriminator key "$type"
    entries: [
      JsonRegistryEntry<Name>(
        type: 'Name',
        serializer: (n) => JsonObject.wrap({'v': n.v}),
        deserializer: (json) => Name(json['v']!.asString.value),
      ),
    ],
  );

  final json = reg.serialize(Name('Zed'));
  print(json.build());
  // {
  //   "$type": "Name",
  //   "v": "Zed"
  // }

  final out = json.asObject.asType<Name>(registry: reg);
  print(out.v); // Zed
}

Matching strategy with predicates

Entries can match by exact runtime type (default) or via a predicate like assignableType:

import 'package:typeson/typeson.dart';

abstract class Animal {}
class Dog implements Animal { final String name; Dog(this.name); }

void main() {
  final reg = JsonRegistry(
    entries: [
      JsonRegistryEntry<Animal>(
        type: 'Animal',
        serializer: (a) => JsonObject.wrap({'name': (a as Dog).name}),
        deserializer: (json) => Dog(json['name']!.asString.value),
        check: JsonRegistryEntry.assignableType<Animal>,
      ),
    ],
  );

  final roundTrip = reg.deserialize(reg.serialize(Dog('Rex')));
  print((roundTrip as Dog).name); // Rex
}

API highlights

• JsonValue
  • factory JsonValue(Object): wrap String/num/bool/List/Map or custom objects via active registry
  • factory JsonValue.parse(String): decode from JSON text
  • factory JsonValue.unsafe(Object): raw wrapper with lazy parsing and zero-copy views
  • toJson(), toEncodeable(), asString/asNumber/asBoolean/asArray/asObject, asType
• JsonString
  • value, split, asBoolean ("true"/"false"), asNumber, maybeAsBoolean, maybeAsNumber
• JsonNumber
  • value, intValue, doubleValue, arithmetic and comparisons, asString
• JsonBoolean
  • value, &, |, ^, ~, asString
• JsonArray
  • value: List<JsonValue?>, iterable, index access/mutation, add/insert/remove variants, containsElement, asMap(), toEncodeable()
• JsonObject
  • value: Map<String, JsonValue?>, iterable, key access/mutation, put/update/remove variants, containsKey/containsValue, toEncodeable(), asType
• Extensions
  • on String/num/bool/List/Map: .json → corresponding JsonValue wrappers
  • on JsonValue: .build({int? indent = 2, bool explicitNulls = false}), .let(...)
  • on Object: .rawJson → JsonValue.unsafe(this)
• JsonBuilder
  • indent, explicitNulls; eliminate nulls in maps by default; preserves nulls in lists
• JsonRegistry / JsonRegistryEntry / JsonObjectParser
  • Envelope ("__type"/"__data") by default; FlatTypeParser with "$type"; custom parsers supported

Notes

• raw.dart is internal; use JsonValue.unsafe(...) or .rawJson instead of importing src directly.
• .build’s null-elimination only removes nulls from maps; it preserves nulls in lists.
• When writing serializers for nested custom types, use JsonRegistry.currentRegistry to ensure nested entries get serialized with the active registry.

Run examples/tests (optional)

You can copy any snippet above into a small Dart app. To run the repo tests locally:

dart pub get
dart test

That’s it—enjoy typed JSON with flexible (de)serialization.