TeaLeaf 2.0.0-beta.14

TeaLeaf

Schema-aware data format with human-readable text and compact binary representation.

Optimized for LLM context engineering -- schemas eliminate repeated field names, reducing data tokens by ~36% compared to JSON with no accuracy loss. Savings increase with larger, more structured datasets.

Features

• Dual formats: Human-readable text (.tl) and compact binary (.tlbx)
• Schema-aware: Automatic struct inference for uniform object arrays
• Type-preserving: Full JSON type fidelity including number types
• High-performance: Native Rust core with zero-copy parsing
• Cross-platform: Windows, Linux, macOS (x64 and ARM64)

Installation

dotnet add package TeaLeaf

Quick Start

using TeaLeaf;

// Convert JSON to TeaLeaf document
string json = """{"name": "Alice", "age": 30}""";
using var doc = TLDocument.FromJson(json);

// Get the TeaLeaf text format (with schema definitions)
string tlText = doc.ToText();

// Convert back to JSON
string roundTrip = doc.ToJson();

// Compile to binary format for compact storage
doc.Compile("data.tlbx", compress: true);

// Read binary file
using var reader = TLReader.Open("data.tlbx");
string fromBinary = reader.ToJson();

// Access values by key
var name = reader.Get("name")?.AsString();

Working with Text Format (.tl)

using TeaLeaf;

// Parse TeaLeaf text
string tlText = """
    @struct Person (name: string, age: int)
    person: @Person ("Alice", 30)
    """;
using var doc = TLDocument.Parse(tlText);

// Access values
var person = doc.Get("person");
Console.WriteLine(person?.GetField("name")?.AsString()); // "Alice"

// Convert to JSON
Console.WriteLine(doc.ToJson());

Working with Binary Format (.tlbx)

using TeaLeaf;

// Create binary from JSON (one step)
TLReader.CreateFromJson(jsonString, "output.tlbx", compress: true);

// Or from a document
using var doc = TLDocument.FromJson(jsonString);
doc.Compile("output.tlbx", compress: true);

// Read binary file
using var reader = TLReader.Open("data.tlbx");

// Access data
foreach (var key in reader.Keys)
{
    Console.WriteLine($"{key}: {reader.GetAsJson(key)}");
}

// Memory-mapped reading for large files
using var mmapReader = TLReader.OpenMmap("large.tlbx");

DTO Serialization

Annotate your classes with [TeaLeaf] for reflection-based serialization:

using TeaLeaf;
using TeaLeaf.Annotations;

[TeaLeaf]
public class Employee
{
    public string Name { get; set; } = "";
    public int Age { get; set; }

    [TLRename("dept")]
    public string Department { get; set; } = "";

    [TLOptional]
    public string? Email { get; set; }
}

// Serialize to TeaLeaf text (with @struct schema)
var emp = new Employee { Name = "Alice", Age = 30, Department = "Engineering" };
string tlText = TeaLeafSerializer.ToDocument(emp);

// Serialize collection to TeaLeaf
var employees = new List<Employee> { emp };
string tableText = TeaLeafSerializer.ToText(employees, "employees");

// Compile directly to binary
TeaLeafSerializer.Compile(emp, "employee.tlbx", compress: true);

// Deserialize from TeaLeaf text
var restored = TeaLeafSerializer.FromText<Employee>(tlText);

// Deserialize from TLDocument
using var doc = TLDocument.Parse(tlText);
var fromDoc = TeaLeafSerializer.FromDocument<Employee>(doc);

Attributes

Source Generator

For compile-time code generation (better performance than reflection), add Generate = true and mark the class as partial:

[TeaLeaf(Generate = true)]
public partial class Employee
{
    public string Name { get; set; } = "";
    public int Age { get; set; }
}

This generates ToTeaLeafText(), FromTeaLeaf(), and other methods at compile time.

Supported Platforms

API Reference

TLDocument

For working with TeaLeaf text format (.tl):

TLReader

For reading binary TeaLeaf files (.tlbx):

TeaLeaf Format Example

JSON input:

{
  "users": [
    {"name": "Alice", "age": 30},
    {"name": "Bob", "age": 25}
  ]
}

TeaLeaf text output (with auto-inferred schema):

@struct User (name: string, age: int)

users: @table User [
  ("Alice", 30)
  ("Bob", 25)
]

License

MIT

Links

• GitHub Repository
• Documentation
• .NET Guide
• Source Generator Guide