TOON Dart SDK

This package aims to deliver an idiomatic Dart implementation of Token-Oriented Object Notation (TOON), optimized for preparing large language model prompts in Flutter and server-side Dart applications. The library will track the capabilities of the official TypeScript toolkit while adopting familiar Dart patterns and tooling.

Project Status

  • 🚧 Pre-alpha: The package is not yet published on pub.dev; APIs remain subject to change.
  • 🎯 Goal: Provide first-class parsing, serialization, and validation utilities that align with the upstream specification and fixtures.
  • 🤝 Feedback welcome: Please open issues to discuss API design, integrations, or edge cases you need covered.

Current Implementation

  • ✅ decode parses root primitives, nested objects, inline arrays, list-form arrays, and tabular collections with length checks, delimiter overrides, and strict indentation validation.
  • ✅ encode emits the same structures (including list/tabular arrays and nested primitive arrays), supports custom delimiters and optional # length markers, and normalises scientific-notation doubles.
  • ✅ Shared fixtures (fixtures/spec/advanced_arrays.*) exercise round-trips alongside the TypeScript and Rust SDKs.
  • ⚠️ Streaming adapters and higher-level codecs are still on the roadmap.

Planned Feature Set

  • Streaming parser that transforms TOON documents into strongly typed Dart models with clear diagnostics.
  • Serializer for emitting TOON from Dart objects while preserving column guards and length hints.
  • Codec adapters for seamless interop with json_serializable, freezed, or manual model classes.
  • Conversion utilities for translating between TOON, JSON, CSV, and YAML streams.
  • Flutter-friendly helpers for packaging TOON prompts and responses inside app workflows.

Getting Started

Until the package is published, include it as a path dependency:

dependencies:
  toon:
    path: ../toon-dart

Quick start

import 'package:toon/toon.dart';

void main() {
  const toon = '''
user:
  id: 1
  timeline[2]{event,year}:
    Launch,2024
    Refactor,2025
  highlights[3]:
    - text: First release
    - text: Multi-SDK fixtures
    - [2]: beta,ready
''';

  final decoded = decode(toon);
  print(decoded);
  // {user: {id: 1, timeline: [{event: Launch, year: 2024}, {event: Refactor, year: 2025}], highlights: [{text: First release}, {text: Multi-SDK fixtures}, [beta, ready]]}}

  final reencoded = encode(decoded, options: const ToonEncodeOptions(delimiter: '|'));
  print(reencoded);
  // user:
  //   id: 1
  //   timeline[2]{event|year}:
  //     Launch|2024
  //     Refactor|2025
  //   highlights[3]:
  //     - text: First release
  //     - text: Multi-SDK fixtures
  //     - [2]: beta|ready
}

⚠️ The API surface is still evolving. Namespaces, classes, and method signatures will change as the implementation matures.

Development Workflow

  1. Install Dart (3.4 or newer) and, if needed, Flutter for integration testing.
  2. Run dart format . and dart analyze before submitting changes.
  3. Add unit tests under test/ covering parsing, serialization, and interoperability scenarios.
  4. Keep fixtures in sync with the reference TypeScript project for consistent behavior across SDKs.

Contributing

Contributions are encouraged! Review the shared TOON specification and open an issue describing proposed features or API changes. Aligning behavior with other language bindings ensures predictable cross-platform usage.

License

The package will be distributed under the MIT License.

Libraries

toond