Installation & Setup

Python Installation

pip install toon-format

The official Python library provides encode/decode functions compatible with Python 3.8+

JavaScript / TypeScript Installation

npm install toon-format
# or
yarn add toon-format

Works in Node.js, browsers, and modern frameworks like React, Next.js, Vue

Python Integration Examples

Basic Encoding

from toon import encode

# Your data
data = [
    {"name": "Alice", "age": 30, "city": "NYC"},
    {"name": "Bob", "age": 25, "city": "LA"},
    {"name": "Charlie", "age": 35, "city": "SF"}
]

# Convert to TOON
toon_string = encode(data, delimiter=",", indent=2)

print(toon_string)
# Output:
# items[3]{name,age,city}:
#   Alice,30,NYC
#   Bob,25,LA
#   Charlie,35,SF

Using with OpenAI API

import openai
from toon import encode

# Database query results
users = fetch_users_from_db()  # Returns list of dicts

# Convert to TOON for efficient prompt
toon_data = encode(users)

# Use in OpenAI prompt
response = openai.ChatCompletion.create(
    model="gpt-4",
    messages=[
        {
            "role": "system",
            "content": "You are a data analyst. Data is in TOON format."
        },
        {
            "role": "user",
            "content": f"""Analyze this user data and provide insights:

{toon_data}

Provide: 1) Most common city, 2) Average age, 3) Trends"""
        }
    ]
)

print(response.choices[0].message.content)

This approach saves 30-50% tokens compared to embedding the full JSON array

Decoding TOON Response

from toon import decode

# If LLM returns TOON format
llm_response = """
items[2]{product,quantity,price}:
  Laptop,5,999
  Mouse,10,25
"""

# Decode back to Python objects
products = decode(llm_response)

# Results in:
# [
#   {"product": "Laptop", "quantity": "5", "price": "999"},
#   {"product": "Mouse", "quantity": "10", "price": "25"}
# ]

for product in products:
    print(f"{product['product']}: {product['quantity']} units")

JavaScript / TypeScript Integration

Basic Usage

import { encode, decode } from 'toon-format';

// Your data
const data = [
  { name: "Alice", age: 30, city: "NYC" },
  { name: "Bob", age: 25, city: "LA" },
  { name: "Charlie", age: 35, city: "SF" }
];

// Convert to TOON
const toonString = encode(data, { 
  delimiter: ",", 
  indent: 2 
});

console.log(toonString);

Next.js API Route Example

// app/api/analyze/route.ts
import { encode } from 'toon-format';
import OpenAI from 'openai';

const openai = new OpenAI();

export async function POST(request: Request) {
  const { data } = await request.json();
  
  // Convert JSON data to TOON
  const toonData = encode(data);
  
  // Send to OpenAI with reduced tokens
  const completion = await openai.chat.completions.create({
    model: "gpt-4",
    messages: [
      {
        role: "system",
        content: "Analyze data in TOON format"
      },
      {
        role: "user",
        content: `Analyze this data:\n\n${toonData}`
      }
    ]
  });
  
  return Response.json({
    analysis: completion.choices[0].message.content,
    tokensUsed: completion.usage?.total_tokens
  });
}

React Hook for TOON Conversion

// hooks/useToon.ts
import { useState, useCallback } from 'react';
import { encode, decode } from 'toon-format';

export function useToon() {
  const [toonOutput, setToonOutput] = useState('');
  
  const convertToToon = useCallback((data: any[]) => {
    const result = encode(data, { delimiter: ',' });
    setToonOutput(result);
    return result;
  }, []);
  
  const convertFromToon = useCallback((toonString: string) => {
    return decode(toonString);
  }, []);
  
  return { toonOutput, convertToToon, convertFromToon };
}

// Usage in component
function MyComponent() {
  const { toonOutput, convertToToon } = useToon();
  
  const handleConvert = () => {
    const data = [
      { id: 1, name: "Item 1" },
      { id: 2, name: "Item 2" }
    ];
    convertToToon(data);
  };
  
  return <div>{toonOutput}</div>;
}

Advanced Configuration Options

Option	Type	Default	Description
delimiter	string	","	Field separator (comma, semicolon, pipe, tab)
indent	number	2	Number of spaces for indentation
showLength	boolean	true	Include length marker (.-) at end
escapeDelimiters	boolean	true	Auto-escape delimiters in values
nullValue	string	"null"	How to represent null values

Example with custom options:

const toon = encode(data, {
  delimiter: ';',
  indent: 4,
  showLength: false,
  nullValue: '∅'
});

Best Practices

✓ DO: Cache TOON conversions

If you're converting the same data repeatedly, cache the TOON string to avoid redundant encoding.

const cache = new Map();

function getToonData(data) {
  const key = JSON.stringify(data);
  if (!cache.has(key)) {
    cache.set(key, encode(data));
  }
  return cache.get(key);
}

✓ DO: Use consistent delimiters

Stick to one delimiter across your application. Comma is most common, but use pipe (|) if your data contains many commas.

✗ DON'T: Use TOON for nested objects

TOON works best with flat tabular data. For deeply nested structures, JSON is more appropriate.

Integrating TOON in Your AI Application