// Encode a Map to TOON
Map<String, Object> data = new Map<String, Object>{
    'id' => 123,
    'name' => 'Ada Lovelace',
    'active' => true,
    'tags' => new List<String>{'developer', 'pioneer'}
};

String toon = toonify.ApexToon.encode(data);
System.debug(toon);

String toon = 'id: 123\nname: Ada Lovelace\nactive: true';
Object decoded = toonify.ApexToon.decode(toon);

Map<String, Object> result = (Map<String, Object>) decoded;
System.debug(result.get('name')); // Ada Lovelace

// JSON to TOON
String json = '{"id":123,"name":"Ada"}';
String toon = toonify.ApexToon.encodeJson(json);

// TOON to JSON
String jsonOutput = toonify.ApexToon.decodeToJson(toon);

// Encode with default options
public static String encode(Object value)

// Encode with custom options
public static String encode(Object value, EncodeOptions options)

// Encode JSON string to TOON
public static String encodeJson(String jsonString)
public static String encodeJson(String jsonString, EncodeOptions options)

// Decode TOON to Object
public static Object decode(String toon)
public static Object decode(String toon, DecodeOptions options)

// Decode TOON to JSON string
public static String decodeToJson(String toon)
public static String decodeToJson(String toon, DecodeOptions options)

// Encode SObjects with field selection
public static String encodeSObjects(List<SObject> records, List<Schema.SObjectField> fields)
public static String encodeSObjects(List<SObject> records, List<String> fieldNames)

// With custom options
public static String encodeSObjects(List<SObject> records, List<Schema.SObjectField> fields, EncodeOptions options)
public static String encodeSObjects(List<SObject> records, List<String> fieldNames, EncodeOptions options)

public class EncodeOptions {
    public Integer indent;              // Spaces per level (default: 2)
    public ToonDelimiter delimiter;     // COMMA, TAB, PIPE (default: COMMA)

    // Constructor with defaults
    public EncodeOptions()

    // Constructor with custom values
    public EncodeOptions(Integer indent, ToonDelimiter delimiter)
}

public class DecodeOptions {
    public Integer indent;              // Expected indent (default: 2)
    public ToonDelimiter delimiter;     // Expected delimiter (default: COMMA)
    public Boolean strict;              // Throw on errors (default: true)
    public PathExpansion expandPaths;   // Path expansion mode (default: SAFE)

    // Constructors
    public DecodeOptions()
    public DecodeOptions(Integer indent, ToonDelimiter delimiter, Boolean strict, PathExpansion expandPaths)
}

public enum ToonDelimiter {
    COMMA,  // Default: value1,value2,value3
    TAB,    // Tab-separated: value1\tvalue2\tvalue3
    PIPE    // Pipe-separated: value1|value2|value3
}

public enum PathExpansion {
    SAFE,   // Expand nested paths when safe
    OFF     // No path expansion
}

// Query records
List<Account> accounts = [
    SELECT Name, Industry, AnnualRevenue
    FROM Account
    LIMIT 100
];

// Define fields to encode
List<Schema.SObjectField> fields = new List<Schema.SObjectField>{
    Account.Name,
    Account.Industry,
    Account.AnnualRevenue
};

// Encode to TOON
String toon = toonify.ApexToon.encodeSObjects(accounts, fields);

// Query with relationships
List<Contact> contacts = [
    SELECT FirstName, LastName, Email, Account.Name, Account.Industry
    FROM Contact
];

// Use field names (supports dot notation)
List<String> fieldNames = new List<String>{
    'FirstName',
    'LastName',
    'Email',
    'Account.Name',
    'Account.Industry'
};

String toon = toonify.ApexToon.encodeSObjects(contacts, fieldNames);

List<Custom_Product__c> products = [
    SELECT SKU__c, Name, Price__c, Inventory_Count__c
    FROM Custom_Product__c
    WHERE Active__c = true
];

List<Schema.SObjectField> fields = new List<Schema.SObjectField>{
    Custom_Product__c.SKU__c,
    Custom_Product__c.Name,
    Custom_Product__c.Price__c,
    Custom_Product__c.Inventory_Count__c
};

String toon = toonify.ApexToon.encodeSObjects(products, fields);

// Use tabs for better spreadsheet compatibility
EncodeOptions opts = new EncodeOptions(2, ToonDelimiter.TAB);
String toon = toonify.ApexToon.encode(data, opts);

// Use pipes for clarity with comma-heavy data
EncodeOptions pipeOpts = new EncodeOptions(2, ToonDelimiter.PIPE);
String toon = toonify.ApexToon.encode(addresses, pipeOpts);

Map<String, Object> complex = new Map<String, Object>{
    'company' => new Map<String, Object>{
        'name' => 'Tech Corp',
        'employees' => new List<Object>{
            new Map<String, Object>{
                'name' => 'Alice',
                'role' => 'Engineer',
                'years' => 5
            },
            new Map<String, Object>{
                'name' => 'Bob',
                'role' => 'Designer',
                'years' => 3
            }
        }
    }
};

String toon = toonify.ApexToon.encode(complex);

try {
    String toon = toonify.ApexToon.encode(data);
} catch (ToonEncodingException e) {
    System.debug('Encoding failed: ' + e.getMessage());
}

try {
    Object result = toonify.ApexToon.decode(toonString);
} catch (ToonDecodingException e) {
    System.debug('Decoding failed: ' + e.getMessage());
}

// Don't throw on parse errors, return null instead
DecodeOptions lenient = new DecodeOptions();
lenient.strict = false;

Object result = toonify.ApexToon.decode(possiblyInvalidToon, lenient);
if (result == null) {
    System.debug('Failed to decode, but no exception thrown');
}

// ✅ Good: Query only needed fields
List<Account> accounts = [SELECT Name, Industry FROM Account];
String toon = toonify.ApexToon.encodeSObjects(accounts,
    new List<Schema.SObjectField>{Account.Name, Account.Industry});

// ❌ Bad: Query all fields then filter
List<Account> accounts = [SELECT FIELDS(ALL) FROM Account];
String toon = toonify.ApexToon.encodeSObjects(accounts, someFields);

// ✅ Good: Batch large datasets
for (Integer i = 0; i < 1000; i += 100) {
    List<SObject> batch = records.subList(i, Math.min(i + 100, 1000));
    String toon = toonify.ApexToon.encodeSObjects(batch, fields);
    // Process batch
}

@IsTest
private class MyApexToonTest {
    @IsTest
    static void testEncodeDecodeRoundTrip() {
        // Given
        Map<String, Object> original = new Map<String, Object>{
            'id' => 123,
            'name' => 'Test',
            'active' => true
        };

        // When
        String toon = toonify.ApexToon.encode(original);
        Object decoded = toonify.ApexToon.decode(toon);

        // Then
        Map<String, Object> result = (Map<String, Object>) decoded;
        Assert.areEqual(123, result.get('id'));
        Assert.areEqual('Test', result.get('name'));
        Assert.areEqual(true, result.get('active'));
    }
}