toon_annotation #

Annotations and configuration classes for toon_serializable, enabling type-safe TOON (Token-Oriented Object Notation) conversion in Dart and Flutter projects.

Features #

• Type-safe annotations for marking classes as TOON-serializable
• Flexible field mapping with customizable naming strategies
• Strict validation options for decoding
• Tabular array support for efficient list serialization

Getting started #

Add toon_annotation to your pubspec.yaml:

dependencies:
  toon_annotation: ^1.0.0

Usage #

Basic Usage #

Annotate your classes with @ToonSerializable() to enable code generation:

import 'package:toon_annotation/toon_annotation.dart';

@ToonSerializable()
class User {
  final String name;
  final int age;
  
  User({required this.name, required this.age});
}

Field Renaming #

Use the fieldRename option to automatically convert field names:

@ToonSerializable(fieldRename: FieldRename.snake)
class User {
  final String firstName;  // Serializes as "first_name"
  final String lastName;    // Serializes as "last_name"
}

Available strategies:

• FieldRename.none - No change (default)
• FieldRename.snake - camelCase → snake_case
• FieldRename.kebab - camelCase → kebab-case
• FieldRename.pascal - camelCase → PascalCase

Custom Field Names #

Override individual field names using @ToonKey():

@ToonSerializable()
class User {
  @ToonKey(name: 'user_id')
  final String id;
  
  @ToonKey(name: 'full_name')
  final String name;
}

Strict Validation #

Enable strict key validation during decoding:

@ToonSerializable(strictKeys: true)
class User {
  final String name;
  final int age;
}

When strictKeys is true, the generated code will report errors for missing or extra fields during decoding.

Tabular Arrays #

Use tabular array format for lists of serializable objects:

@ToonSerializable(useTabularArrays: true)
class UserList {
  final List<User> users;  // Serializes as a TOON tabular array
}

Additional information #

This package provides the annotations used by the toon_serializable code generator. For code generation, you'll also need to add toon_serializable as a dev dependency and configure the build runner.

For more information about TOON format and the code generator, see the toon_serializable package documentation.