toon_serializable #

The official code generator for Token-Oriented Object Notation (TOON) models in Dart. Automatically generates TOON serialization code using build_runner.

Features #

• 🚀 Automatic Code Generation: Generate toToon() and fromToon() methods with a single annotation
• 🔄 Field Renaming: Support for multiple field renaming strategies (snake_case, kebab-case, PascalCase, camelCase)
• 🎯 Custom Keys: Override field names with @ToonKey annotation
• 📦 Type Safety: Full support for nullable types and generic lists
• ⚡ Zero Runtime Overhead: All serialization logic is generated at compile time
• 🔧 Easy Integration: Works seamlessly with build_runner and existing Dart projects

Installation #

Add the following to your pubspec.yaml:

dependencies:
  toon_annotation: ^1.0.0
  toon_dart: ^1.0.0

dev_dependencies:
  toon_serializable: ^1.0.1
  build_runner: ^2.10.3

Then run:

dart pub get

Configuration #

The package is automatically configured via build.yaml. No manual configuration is required for most use cases.

Usage #

Basic Example #

1. Define your model class with the @ToonSerializable annotation:

import 'package:toon_annotation/toon_annotation.dart';
import 'package:toon_dart/toon_dart.dart';

part 'user_model.toon_serializable.g.part'; // Generated file

@ToonSerializable()
class User {
  final String name;
  final int age;
  
  User({required this.name, required this.age});
  
  // These methods will be generated
  factory User.fromToon(String toon) => _$UserFromToon(toon);
  String toToon() => _$UserToToon(this);
}

2. Run the code generator:

dart run build_runner build

3. Use the generated code:

final user = User(name: 'Alice', age: 30);
final toonString = user.toToon(); // Serialize to TOON
final decodedUser = User.fromToon(toonString); // Deserialize from TOON

Field Renaming #

Use fieldRename to automatically convert field names:

@ToonSerializable(fieldRename: FieldRename.snake)
class User {
  final String firstName; // Serializes as 'first_name'
  final int userAge;      // Serializes as 'user_age'
  
  User({required this.firstName, required this.userAge});
  
  factory User.fromToon(String toon) => _$UserFromToon(toon);
  String toToon() => _$UserToToon(this);
}

Custom Field Keys #

Override specific field names with @ToonKey:

@ToonSerializable(fieldRename: FieldRename.snake)
class User {
  final String firstName; // Serializes as 'first_name'
  
  @ToonKey(name: 'user_age')
  final int age; // Serializes as 'user_age' (not 'age')
  
  User({required this.firstName, required this.age});
  
  factory User.fromToon(String toon) => _$UserFromToon(toon);
  String toToon() => _$UserToToon(this);
}

Advanced Options #

@ToonSerializable(
  fieldRename: FieldRename.snake,
  useTabularArrays: false, // Set to true for tabular array format
  strictKeys: true,        // Enable strict key validation
)
class User {
  // ... your fields
}

Running the Generator #

One-time Generation #

dart run build_runner build

Watch Mode (Auto-regenerate on file changes) #

dart run build_runner watch

Clean Build (Delete conflicting outputs) #

dart run build_runner build --delete-conflicting-outputs

Important Notes #

⚠️ Known Issue: Part Declaration #

The generated .part file requires manual addition of the part of declaration.

After running build_runner, you must manually add the following line at the top of each generated .part file:

part of 'your_file_name.dart';

For example, if your file is user_model.dart and the generated file is user_model.toon_serializable.g.part, add:

part of 'user_model.dart';

// ... rest of generated code

Why is this needed? The SharedPartBuilder from source_gen should automatically add this declaration, but due to current limitations, it must be added manually. This is a known issue that will be addressed in a future release.

Workaround: You can create a simple script or use your IDE's find-and-replace to add this line after each code generation.

Field Renaming Strategies #

Supported Types #

• Primitives: String, int, double, bool
• Nullable types: String?, int?, etc.
• Lists: List<String>, List<int>, etc.
• Nested objects: Any class annotated with @ToonSerializable
• Maps: Map<String, dynamic> (via toon_dart)

Examples #

See the /example directory for complete working examples.

Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

Issues #

If you encounter any issues or have feature requests, please file them on the issue tracker.

License #

This package is licensed under the MIT License. See the LICENSE file for details.

Related Packages #

• toon_annotation - Annotation definitions
• toon_dart - Low-level TOON parser