Skip to main content

ToonNet API Guide: System.Text.Json Style

Design Philosophy​

ToonNet's API follows the patterns of System.Text.Json (Serialize/Deserialize with optional options) - if you know System.Text.Json, ToonNet will feel familiar.


API Comparison​

System.Text.Json API​

using System.Text.Json;

// Serialize
string json = JsonSerializer.Serialize(person);
string withOptions = JsonSerializer.Serialize(person, options);

// Deserialize
Person? p = JsonSerializer.Deserialize<Person>(json);
Person? p2 = JsonSerializer.Deserialize<Person>(json, options);

ToonNet API (Same Pattern)​

using ToonNet.Core.Serialization;
using ToonNet.Extensions.Json; // For JSON conversion methods

// Serialize to TOON
string toon = ToonSerializer.Serialize(person);
string withOptions = ToonSerializer.Serialize(person, options);

// Deserialize from TOON
Person? p = ToonSerializer.Deserialize<Person>(toon);
Person? p2 = ToonSerializer.Deserialize<Person>(toon, options);

// UTF-8, as JsonSerializer.SerializeToUtf8Bytes and Deserialize(ReadOnlySpan<byte>)
byte[] utf8 = ToonSerializer.SerializeToUtf8Bytes(person);
Person? p3 = ToonSerializer.Deserialize<Person>(utf8);

// JSON ↔ TOON conversion (ToonNet.Extensions.Json package)
string fromJson = ToonConvert.FromJson(jsonString); // JSON → TOON
string json = ToonConvert.ToJson(toonString); // TOON → JSON

Common Operations​

1. C# Object → TOON (Standard Serialization)​

var person = new Person { Name = "John", Age = 30 };
string toon = ToonSerializer.Serialize(person);

// Output:
// Name: John
// Age: 30

2. TOON → C# Object (Standard Deserialization)​

string toon = "Name: John\nAge: 30";
var person = ToonSerializer.Deserialize<Person>(toon)!;

Console.WriteLine(person.Name); // "John"
Console.WriteLine(person.Age); // 30

Bytes, character spans and streams are read without an intermediate string, and objects can be written as UTF-8 to a byte[], an IBufferWriter<byte> or a Stream:

var fromBytes = ToonSerializer.Deserialize<Person>(utf8Bytes); // ReadOnlySpan<byte>
var fromStream = ToonSerializer.Deserialize<Person>(stream); // read to the end
ToonSerializer.Serialize(pipeWriter, person); // IBufferWriter<byte>

3. JSON String → TOON String​

string json = """{"name": "John", "age": 30}""";
string toon = ToonConvert.FromJson(json);

// Output:
// name: John
// age: 30

4. TOON String → JSON String​

string toon = "name: John\nage: 30";
string json = ToonConvert.ToJson(toon);

// Output: {"name":"John","age":30}

5. JSON String → C# Object​

string json = """{"Name": "John", "Age": 30}""";

// Plain System.Text.Json deserialization (optional JsonSerializerOptions)
var person = ToonConvert.DeserializeFromJson<Person>(json);

// Converts the JSON to TOON first, then deserializes with ToonSerializer (optional ToonSerializerOptions)
var person2 = ToonConvert.ParseJson<Person>(json);

6. C# Object → JSON String​

var person = new Person { Name = "John", Age = 30 };
string json = ToonConvert.SerializeToJson(person); // System.Text.Json, indented by default

// Output:
// {
// "Name": "John",
// "Age": 30
// }

Real-World Examples​

Example 1: API Response (JSON → TOON)​

// You receive JSON from an API
var response = await httpClient.GetStringAsync("https://api.example.com/users/123");

// Convert to TOON format (more readable for logs/debugging)
string toonLog = ToonConvert.FromJson(response);

// Log it (a message template, not an interpolated string)
logger.LogInformation("User data:\n{User}", toonLog);

// Output in logs:
// User data:
// id: 123
// name: John Doe
// email: john@example.com
// isActive: true

Example 2: Config Files (TOON ↔ JSON)​

// Load TOON config (human-readable)
string toonConfig = await File.ReadAllTextAsync("appsettings.toon");

// Convert to JSON for System.Text.Json consumers
string jsonConfig = ToonConvert.ToJson(toonConfig);

var config = JsonSerializer.Deserialize<AppSettings>(jsonConfig);

For IConfiguration, read the TOON file directly with builder.Configuration.AddToonFile("appsettings.toon") (the configuration provider of ToonNet.AspNetCore).

Example 3: Data Migration​

// You have JSON data files
var jsonFiles = Directory.GetFiles("data", "*.json");

foreach (var jsonFile in jsonFiles)
{
// Read JSON
string json = await File.ReadAllTextAsync(jsonFile);

// Convert to TOON (smaller, especially for arrays of uniform objects)
string toon = ToonConvert.FromJson(json);

// Save as TOON
var toonFile = Path.ChangeExtension(jsonFile, ".toon");
await File.WriteAllTextAsync(toonFile, toon);

Console.WriteLine($"Converted: {jsonFile} → {toonFile}");
}

Example 4: Webhook Logging​

app.MapPost("/webhook", async (HttpRequest request, ILogger<Program> logger) =>
{
// Read JSON payload
using var reader = new StreamReader(request.Body);
string jsonPayload = await reader.ReadToEndAsync();

// Convert to TOON for readable logs
string toonPayload = ToonConvert.FromJson(jsonPayload);

// Log it; payloads can hold personal data (emails, names): log only what your privacy rules allow
logger.LogInformation("Webhook received:\n{Payload}", toonPayload);

return Results.Ok();
});

Package Installation​

dotnet add package ToonNet.Core
dotnet add package ToonNet.Extensions.Json # for ToonConvert (JSON ↔ TOON)

ToonSerializer is in ToonNet.Core; the JSON conversion methods (ToonConvert) are in ToonNet.Extensions.Json.


Which API to Use​

ToonConvert converts between JSON and TOON text in one call, as JsonSerializer does between objects and JSON. When you need the tree in between (to change it, query it or write it with other options), use the lower-level types ToonConvert is built on:

using ToonNet.Core.Encoding;
using ToonNet.Extensions.Json;

string toon = ToonConvert.FromJson(json); // text to text
string json2 = ToonConvert.ToJson(toon);

var document = ToonJsonConverter.FromJson(json); // a ToonDocument
document.Root.RemoveAll("$..password");
string trimmed = new ToonEncoder().Encode(document);

Conversion Matrix​

FromToMethodExample
C# ObjectTOONSerialize()ToonSerializer.Serialize(person)
TOONC# ObjectDeserialize<T>()ToonSerializer.Deserialize<Person>(toon)
JSONTOONFromJson()ToonConvert.FromJson(json)
TOONJSONToJson()ToonConvert.ToJson(toon)
JSONC# ObjectDeserializeFromJson<T>()ToonConvert.DeserializeFromJson<Person>(json) (System.Text.Json)
JSONC# Object (via TOON)ParseJson<T>()ToonConvert.ParseJson<Person>(json)
C# ObjectJSONSerializeToJson()ToonConvert.SerializeToJson(person)

Async and Streaming Serialization​

For large datasets (millions of records, database exports, ETL pipelines), ToonNet provides memory-efficient streaming serialization:

Basic Streaming​

// Stream large dataset from database without loading all into memory
await ToonSerializer.SerializeDocumentsAsync(
items: dbContext.Users.AsAsyncEnumerable(),
filePath: "users_export.toon",
cancellationToken: cts.Token
);

// Read back with incremental deserialization
await foreach (var user in ToonSerializer.DeserializeDocumentsAsync<User>("users_export.toon"))
{
ProcessUser(user); // Memory-efficient: only one user in memory at a time
}

Advanced Configuration​

// Custom separator mode and batch size for optimal performance
await ToonSerializer.SerializeDocumentsAsync(
items: GenerateLargeDatasetAsync(),
filePath: "export.toon",
options: null,
writeOptions: new ToonMultiDocumentWriteOptions
{
Mode = ToonMultiDocumentSeparatorMode.ExplicitSeparator, // Use "---" separator
DocumentSeparator = "---",
BatchSize = 100 // Buffer 100 items before writing (improves throughput)
},
cancellationToken: cts.Token
);

// Read it back in the same mode: the default (blank-line) reader does not recognize "---"
// and fails with a ToonParseException ("Missing colon after key")
await foreach (var item in ToonSerializer.DeserializeDocumentsAsync<Item>(
"export.toon",
options: null,
ToonMultiDocumentReadOptions.ExplicitSeparator))
{
Process(item);
}

One Large Root Array​

A single document that is one large root array ([200000]{id,name}: followed by rows, as ToonSerializer.Serialize(list) writes it) can be read item by item, a batch of about 32 KB at a time:

await using var stream = File.OpenRead("users.toon");

await foreach (var user in ToonSerializer.DeserializeAsyncEnumerable<User>(stream))
{
ProcessUser(user);
}

The root must be an array: an array under a key (users[200000]{id,name}:) is an object and throws a ToonSerializationException. Errors and line numbers are those of reading the whole document.

An Array Inside a Document​

DeserializeAsyncEnumerableAt streams the items of an array at a path of member names, such as the rows of a response envelope; the stream is read no further than the end of the array:

await foreach (var order in ToonSerializer.DeserializeAsyncEnumerableAt<Order>(response, "$.data.orders"))
{
Process(order);
}

Querying, Editing and Language Models​

JSONPath (RFC 9535)​

using ToonNet.Core.Models;
using ToonNet.Core.Paths;
using ToonNet.Core.Serialization;

var root = ToonDocument.Parse(toon).Root;
var ids = root.Select("$.orders[?@.total > 100 && @.paid == true].id"); // on a tree
var fromText = ToonPath.Parse("$.orders[?@.total > 100]").SelectFrom(toon); // straight from text, building only the matches

var orders = ToonSerializer.DeserializeAt<List<Order>>(toon, "$.data.orders"); // one value, the rest skipped
var big = ToonSerializer.DeserializeAll<Order>(toon, "$.data.orders[?@.total > 100]"); // every match, into objects

Like JsonNode, values have indexers, GetValue<T>(), DeepClone() and ToonValue.DeepEquals; paths set and remove values (root.SetValue("$.meta.by", "x"), root.RemoveAll("$.users[?@.active == false]")), and ToonMergePatch applies and creates JSON Merge Patches (RFC 7386).

ToonSerializer.Deserialize<T>(ToonDocumentReader reader) reads the value a reader is on, as JsonSerializer reads from a Utf8JsonReader.

Functions and Rules​

Filters can call ToonNet functions besides the standard five: starts_with, ends_with, contains (strings and arrays), equals_ignore_case, lower, upper, trim, type, sum, min, max, avg; register your own with ToonPathFunctions in ToonPathOptions.Functions (StandardFunctionsOnly keeps paths portable).

using ToonNet.Core.Validation;

var rules = new ToonRuleSet()
.Rule("$.orders[*]", "sum(@.lines[*].price) == @.total", "The lines do not add up")
.Unique("$.orders[*].id", "Order id {value} repeats");

rules.Validate(toon).ThrowIfInvalid(); // ToonRuleException with the path of each violation

Prompts and Answers​

using ToonNet.Core.Llm;

var context = ToonPrompt.Serialize(orders, new ToonPromptOptions { MaxArrayItems = 50 }); // shortened, "# 380 more items"
var shape = ToonPrompt.DescribeShape<Summary>(); // a TOON template of the answer
var summary = ToonPrompt.Deserialize<Summary>(answer); // the ```toon block of the answer, in non-strict mode

See Querying, Rules and Validation, Editing Trees and Language Models for details.

Use Cases​

Use CaseDescription
Database ExportsStream large result sets (IAsyncEnumerable<T>) to a file without materializing them
ETL PipelinesProcess large files one document at a time
Log ProcessingRead multi-document TOON files incrementally
Data MigrationConvert large datasets with cancellable operations

Performance Characteristics​

  • Memory: Independent of the number of items - roughly BatchSize × ItemSize is buffered while writing
  • Batching: Items are written in batches (BatchSize, default 50) to reduce the number of I/O calls
  • Separators: Documents are separated by a blank line (default) or by DocumentSeparator (default ---) on its own line
  • Cancellation: Full CancellationToken support for long-running operations

API Methods:

// File-based streaming
ValueTask SerializeDocumentsAsync<T>(
IAsyncEnumerable<T> items,
string filePath,
ToonSerializerOptions? options = null,
CancellationToken cancellationToken = default);

// Stream-based with custom options
ValueTask SerializeDocumentsAsync<T>(
IAsyncEnumerable<T> items,
Stream stream,
ToonSerializerOptions? options,
ToonMultiDocumentWriteOptions writeOptions,
CancellationToken cancellationToken = default);

// Incremental deserialization
IAsyncEnumerable<T?> DeserializeDocumentsAsync<T>(
string filePath,
ToonSerializerOptions? options = null,
CancellationToken cancellationToken = default);

// Same, with the separator mode the file was written with (also for a StreamReader)
IAsyncEnumerable<T?> DeserializeDocumentsAsync<T>(
string filePath,
ToonSerializerOptions? options,
ToonMultiDocumentReadOptions multiDocumentOptions,
CancellationToken cancellationToken = default);

// The items of one root array (also with a ToonTypeInfo<T> for trimming and NativeAOT)
IAsyncEnumerable<T?> DeserializeAsyncEnumerable<T>(
Stream utf8Stream,
ToonSerializerOptions? options = null,
CancellationToken cancellationToken = default);

Round-Trip Guarantees​

Understanding Roundtrip Behavior​

ToonNet gives two kinds of round-trip guarantees, depending on the use case:

Strongly Typed Round Trips Preserve Values​

When using strongly-typed serialization with C# classes, property values are preserved:

// Original object
var order = new Order
{
OrderId = "ORD-123",
Discount = 35.00m, // decimal
Total = 100.50m
};

// Round trip through TOON
string toon = ToonSerializer.Serialize(order);
var order2 = ToonSerializer.Deserialize<Order>(toon)!;

// Values match: the TOON text contains "Discount: 35", which reads back as 35m
Assert.Equal(35.00m, order2.Discount); // decimal equality ignores the scale (35.00m == 35m)

public record Order
{
public string OrderId { get; init; } = "";
public decimal Discount { get; init; }
public decimal Total { get; init; }
public string Status { get; init; } = "";
}

Guarantee: If you serialize a C# object to TOON and deserialize back to the same type, the property values are equal to the originals. Numbers are written in canonical form, so a decimal's scale (trailing zeros such as 35.00) is not kept, and long/decimal values are read back exactly.


Format Conversion Preserves Meaning​

When using format conversion between JSON/TOON strings, semantic equivalence is guaranteed, but format details may change:

// Original JSON
string json = @"{ ""discount"": 35.00 }";

// Convert: JSON → TOON → JSON
string toon = ToonConvert.FromJson(json); // discount: 35
string json2 = ToonConvert.ToJson(toon); // {"discount":35}

// ⚠️ Format changed: 35.00 → 35
// ✅ Semantically equivalent: 35.00 == 35 (same value)

What changes in format conversion:

  • ❌ Decimal trailing zeros: 35.00 → 35 (semantically equal)
  • ❌ Whitespace: indentation, line breaks (cosmetic)
  • ❌ Number representation: 1e2 → 100 (semantically equal)

What is guaranteed:

  • ✅ All property names preserved
  • ✅ Property order preserved
  • ✅ All values preserved (semantic equality)
  • ✅ All nested structures preserved
  • ✅ null/true/false preserved exactly
  • ✅ String content preserved exactly

Compared With JSON Libraries​

LibraryDecimal FormatWhitespaceProperty Order
System.Text.Json (JsonElement/JsonNode)PreservedNot preservedPreserved
Newtonsoft.Json (JToken)PreservedNot preservedPreserved
ToonNet (JSON ↔ TOON)Not preservedNot preservedPreserved

Example from System.Text.Json:

string json1 = @"{ ""value"": 35.00 }";
var obj = JsonSerializer.Deserialize<JsonElement>(json1);
string json2 = JsonSerializer.Serialize(obj);
// Result: {"value":35.00} ← JsonElement keeps the original number text; ToonNet normalizes it

Best Practices​

Use Typed Serialization for Application Data​

// Recommended: values round-trip exactly (Order is the record above)
var order = ToonSerializer.Deserialize<Order>(toonString)!;
var modified = order with { Status = "Shipped" };
string toon = ToonSerializer.Serialize(modified);
// Values preserved (Discount reads back as 35m, equal to 35.00m)

Use Format Conversion for Data Exchange​

// ⚠️ USE CASE: Converting between formats (files, APIs)
string json = await File.ReadAllTextAsync("order.json");
string toon = ToonConvert.FromJson(json);
await File.WriteAllTextAsync("order.toon", toon);
// Data preserved, format details may change (this is OK for data exchange)

Compare Values, Not Text​

// ❌ BAD: String comparison will fail due to format differences
string json1 = @"{ ""discount"": 35.00 }";
string json2 = ToonConvert.ToJson(ToonConvert.FromJson(json1));
Assert.Equal(json1, json2); // ❌ FAILS: "35.00" vs "35"

// ✅ GOOD: Semantic comparison
var obj1 = JsonSerializer.Deserialize<JsonElement>(json1);
var obj2 = JsonSerializer.Deserialize<JsonElement>(json2);
Assert.Equal(obj1.GetProperty("discount").GetDecimal(),
obj2.GetProperty("discount").GetDecimal()); // ✅ PASSES

Summary​

ScenarioRoundtrip TypeGuaranteeUse When
C# → TOON → C#Type-SafeValue PreservationProduction code, data storage
JSON → TOON → JSONFormat ConversionSemantic EquivalenceFile conversion, API integration
YAML → TOON → YAMLFormat ConversionSemantic EquivalenceConfig file migration

Key Takeaway:

  • Need value preservation? → Use strongly-typed serialization ✅
  • Need format conversion? → Expect semantic equivalence (values match, format may differ) ⚠️

JSON consumers that read numbers by value treat 35.00 and 35 as the same number, so the converted data is equivalent even though the text differs.


Building Trees in Code​

Just like System.Text.Json allows manual creation of JsonDocument, JsonElement, and JsonObject, ToonNet allows you to manually construct ToonObject, ToonArray, and other ToonValue types.

System.Text.Json Manual Construction​

using System.Text.Json.Nodes;

// Manual JsonObject construction
var jsonObject = new JsonObject
{
["name"] = "John",
["age"] = 30,
["isActive"] = true
};

string json = jsonObject.ToJsonString();
// Output: {"name":"John","age":30,"isActive":true}

ToonNet Manual Construction (Same Pattern)​

using ToonNet.Core.Models;
using ToonNet.Core.Encoding;

// ToonObject construction with implicit conversions
var toonObject = new ToonObject
{
["name"] = "John", // string → ToonString (implicit!)
["age"] = 30, // int → ToonNumber (implicit!)
["isActive"] = true // bool → ToonBoolean (implicit!)
};

var encoder = new ToonEncoder();
string toon = encoder.Encode(new ToonDocument(toonObject));

// Output:
// name: John
// age: 30
// isActive: true

Complete Manual Construction Examples​

A Simple Object​

// Create a user object with implicit conversions
var user = new ToonObject
{
["id"] = 123, // int → ToonNumber
["name"] = "Alice", // string → ToonString
["email"] = "alice@example.com", // string → ToonString
["isVerified"] = true // bool → ToonBoolean
};

// Encode to TOON string
var document = new ToonDocument(user);
var encoder = new ToonEncoder();
string toon = encoder.Encode(document);

Console.WriteLine(toon);
// Output:
// id: 123
// name: Alice
// email: alice@example.com
// isVerified: true

Note: You can also use explicit construction if preferred: ["name"] = new ToonString("Alice"), but implicit conversions make code cleaner.

Nested Objects​

// Create nested objects with implicit conversions
var address = new ToonObject
{
["street"] = "123 Main St",
["city"] = "New York",
["zipCode"] = "10001"
};

var user = new ToonObject
{
["name"] = "Bob",
["age"] = 35,
["address"] = address // Nested object
};

var document = new ToonDocument(user);
var encoder = new ToonEncoder();
string toon = encoder.Encode(document);

Console.WriteLine(toon);
// Output:
// name: Bob
// age: 35
// address:
// street: 123 Main St
// city: New York
// zipCode: "10001" (quoted: an unquoted 10001 would read back as a number)

Arrays​

// Create an array with implicit conversions
var numbers = new ToonArray();
numbers.Add(10); // int → ToonNumber
numbers.Add(20); // int → ToonNumber
numbers.Add(30); // int → ToonNumber

var document = new ToonDocument(numbers);
var encoder = new ToonEncoder();
string toon = encoder.Encode(document);

Console.WriteLine(toon);
// Output:
// [3]: 10,20,30

Arrays of Objects​

// Create an array of objects with implicit conversions
var users = new ToonArray
{
Items =
{
new ToonObject
{
["name"] = "Alice",
["age"] = 25
},
new ToonObject
{
["name"] = "Bob",
["age"] = 30
},
new ToonObject
{
["name"] = "Charlie",
["age"] = 35
}
}
};

var document = new ToonDocument(users);
var encoder = new ToonEncoder();
string toon = encoder.Encode(document);

Console.WriteLine(toon);
// Output (uniform objects use the tabular form; uniform nested objects become nested field groups):
// [3]{name,age}:
// Alice,25
// Bob,30
// Charlie,35

A Nested Structure​

// Create a complex order object with implicit conversions
var order = new ToonObject
{
["orderId"] = "ORD-123",
["customer"] = new ToonObject
{
["name"] = "John Doe",
["email"] = "john@example.com"
},
["items"] = new ToonArray
{
Items =
{
new ToonObject
{
["product"] = "Laptop",
["quantity"] = 1,
["price"] = 999.99
},
new ToonObject
{
["product"] = "Mouse",
["quantity"] = 2,
["price"] = 25.50
}
}
},
["total"] = 1050.99,
["isPaid"] = true
};

// The indexer stores null as ToonNull.Instance
order["notes"] = null;

var document = new ToonDocument(order);
var encoder = new ToonEncoder();
string toon = encoder.Encode(document);

Console.WriteLine(toon);
// Output:
// orderId: ORD-123
// customer:
// name: John Doe
// email: john@example.com
// items[2]{product,quantity,price}:
// Laptop,1,999.99
// Mouse,2,25.5
// total: 1050.99
// isPaid: true
// notes: null

Available ToonValue Types​

TypeConstructorImplicit ConversionExample
ToonNullToonNull.Instancenull through the indexersobj["key"] = null
ToonBooleannew ToonBoolean(bool)✅ booltrue → ToonBoolean
ToonNumbernew ToonNumber(double) (also float, long, ulong, decimal)✅ int, long, float, double, decimal42 → ToonNumber
ToonStringnew ToonString(string)✅ string (non-null)"Hello" → ToonString
ToonObjectnew ToonObject()❌ (use explicit)new ToonObject { ["key"] = value }
ToonArraynew ToonArray()❌ (use explicit)new ToonArray { Items = { value1, value2 } }

Note: Null strings (string? value = null) convert to ToonNull.Instance via ToonValue implicit operator.


When to Build Trees in Code​

✅ Use manual construction when:

  • Building TOON documents dynamically from non-C# sources
  • Creating test data for unit tests
  • Implementing custom serialization logic
  • Working with APIs that return structured data
  • Building configuration generators
  • Creating TOON templates programmatically

✅ Use high-level serialization when:

  • Converting C# objects to TOON (use ToonSerializer.Serialize())
  • Converting JSON to TOON (use ToonConvert.FromJson())
  • Working with strongly-typed C# models

Comparison: System.Text.Json vs ToonNet​

OperationSystem.Text.JsonToonNet (Implicit)ToonNet (Explicit)
Create Objectnew JsonObject()new ToonObject()new ToonObject()
Add Stringobj["key"] = "value"obj["key"] = "value"obj["key"] = new ToonString("value")
Add Numberobj["key"] = 42obj["key"] = 42obj["key"] = new ToonNumber(42)
Add Booleanobj["key"] = trueobj["key"] = trueobj["key"] = new ToonBoolean(true)
Add Nullobj["key"] = nullobj["key"] = nullobj["key"] = ToonNull.Instance
Create Arraynew JsonArray()new ToonArray()new ToonArray()
Add Itemarray.Add(42)array.Add(42)array.Add(new ToonNumber(42))
Encodeobj.ToJsonString()encoder.Encode(new ToonDocument(obj))Same

ToonNet supports both implicit conversions (like System.Text.Json) and explicit construction.

Encoding a Tree​

ToonEncoder (namespace ToonNet.Core.Encoding, created with optional ToonOptions) writes a ToonDocument:

MethodWrites
Encode(document)A string
EncodeToUtf8Bytes(document)UTF-8 bytes, without a byte order mark
Encode(document, IBufferWriter<byte>)UTF-8 to a buffer writer (a PipeWriter, an ArrayBufferWriter<byte>)
EncodeAsync(document, ct)A string, asynchronously
EncodeToStreamAsync(document, stream, ct)UTF-8 to a stream, in chunks through pooled buffers
EncodeToFileAsync(document, filePath, ct)UTF-8 to a file, written after the encoding succeeded

An instance keeps no per-call state; AddToonNet registers one as a singleton.


Thread-Safety​

ToonSerializer and a shared ToonEncoder are safe to use from several threads; see Configuration for the caches and options.