turbo_serializable #

A serialization abstraction for the turbo ecosystem with multi-format support (JSON, YAML, Markdown, XML).

Features #

• Primary format specification - Implement one format, get automatic conversion to all others
• Multi-format support - JSON, YAML, Markdown, and XML serialization
• Standalone converters - 12 format conversion functions for direct use
• Typed metadata - Generic M parameter for frontmatter and auxiliary data
• Typed identifiers - TurboSerializableId<T, M> for objects with unique IDs
• Local state tracking - Track whether instances are synced to remote
• Validation integration - Built-in validation using TurboResponse

Installation #

dependencies:
  turbo_serializable: ^0.1.0

Quick Start #

import 'package:turbo_serializable/turbo_serializable.dart';

class User extends TurboSerializable<void> {
  final String name;
  final int age;

  User({required this.name, required this.age});

  @override
  Map<String, dynamic>? toJsonImpl() => {'name': name, 'age': age};
}

void main() {
  final user = User(name: 'Alice', age: 30);

  print(user.toJson());     // {name: Alice, age: 30}
  print(user.toYaml());     // name: Alice\nage: 30
  print(user.toXml());      // <User><name>Alice</name><age>30</age></User>
  print(user.toMarkdown()); // ## Name\nAlice\n\n## Age\n30
}

API Reference #

Classes #

TurboSerializable Methods #

Standalone Converters #

Examples #

With Typed Identifier #

class Product extends TurboSerializableId<String, void> {
  final String productId;
  final String name;
  final double price;

  Product({
    required this.productId,
    required this.name,
    required this.price,
    super.isLocalDefault = false,
  });

  @override
  String get id => productId;

  @override
  Map<String, dynamic>? toJsonImpl() => {
    'id': id,
    'name': name,
    'price': price,
  };
}

With Typed Metadata #

class Frontmatter {
  final String title;
  final List<String> tags;
  Frontmatter({required this.title, required this.tags});
}

class Document extends TurboSerializable<Frontmatter> {
  final String content;

  Document({
    required this.content,
    super.metaData,
    super.primaryFormat = SerializationFormat.markdown,
  });

  @override
  String? toMarkdownImpl() => content;
}

final doc = Document(
  content: '# Hello World',
  metaData: Frontmatter(title: 'My Doc', tags: ['example']),
);
print(doc.metaData?.title); // 'My Doc'

With Validation #

class User extends TurboSerializable<void> {
  final String name;
  final int age;

  User({required this.name, required this.age});

  @override
  TurboResponse<T>? validate<T>() {
    if (name.isEmpty) return TurboResponse.fail(error: 'Name required');
    if (age < 0) return TurboResponse.fail(error: 'Invalid age');
    return null;
  }

  @override
  Map<String, dynamic>? toJsonImpl() => {'name': name, 'age': age};
}

Standalone Converters #

// JSON to other formats
final yaml = jsonToYaml({'name': 'Test', 'age': 25});
final xml = mapToXml({'name': 'Test'}, rootElementName: 'User');

// Parse YAML/XML back to JSON
final json = yamlToJson('name: Test\nage: 25');
final map = xmlToMap('<User><name>Test</name></User>');

// Markdown with frontmatter
final md = jsonToMarkdown(
  {'content': 'Hello'},
  metaData: {'title': 'Test', 'author': 'Me'},
);
// Output:
// ---
// title: Test
// author: Me
// ---
// ## Content
// Hello

License #

MIT