TOON Format Implementation Guide for JavaScript Developers

Building modern JavaScript applications means constantly dealing with data serialization. Whether you're converting JSON to TOON, optimizing LLM API calls, or reducing token costs on ChatGPT/Claude integrations, JavaScript developers need practical, production-ready implementation guides.

This comprehensive guide walks you through implementing the TOON format (Token-Oriented Object Notation) in your JavaScript applications. You'll learn how to integrate the @toon-format/toon library, work with Node.js, build Express.js APIs optimized for LLMs, and achieve 30-60% token reduction compared to traditional JSON encoding.

What is TOON Format and Why JavaScript Developers Should Care

The Problem: JSON's Token Inefficiency

When sending data to Large Language Model APIs (OpenAI, Anthropic, Google), every token costs money. Consider this customer dataset in JSON:

{
  "customers": [
    { "id": 1, "name": "Alice Smith", "email": "alice@example.com", "status": "active", "plan": "premium" },
    { "id": 2, "name": "Bob Johnson", "email": "bob@example.com", "status": "active", "plan": "basic" },
    { "id": 3, "name": "Charlie Brown", "email": "charlie@example.com", "status": "inactive", "plan": "free" }
  ]
}

This JSON uses 187 tokens to represent just 3 customer records.

The Solution: TOON Format

The exact same data in TOON format:

customers[3]{id,name,email,status,plan}:
  1,Alice Smith,alice@example.com,active,premium
  2,Bob Johnson,bob@example.com,active,basic
  3,Charlie Brown,charlie@example.com,inactive,free

This TOON uses only 72 tokens — a 61.5% reduction.

Why Modern JavaScript Developers Need TOON

• ✅ LLM Cost Optimization - Direct impact on API bills
• ✅ Faster Inference - Fewer tokens = faster model response
• ✅ Better Accuracy - Explicit structure helps models parse data correctly
• ✅ Drop-in Replacement - Works seamlessly with existing JavaScript workflows
• ✅ Growing Ecosystem - Official Node.js library with full feature support

Installation & Setup: Getting TOON into Your Project

Step 1: Install the TOON Package

The official TOON JavaScript library is available on npm as @toon-format/toon.

Using npm:

npm install @toon-format/toon

Using yarn:

yarn add @toon-format/toon

Using pnpm:

pnpm add @toon-format/toon

Step 2: Import and Verify Installation

CommonJS syntax:

const { encode, decode } = require('@toon-format/toon');

const data = { users: [{ id: 1, name: 'Alice' }] };
const toonString = encode(data);
console.log(toonString);

ES6 module syntax (recommended):

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

const data = { users: [{ id: 1, name: 'Alice' }] };
const toonString = encode(data);
console.log(toonString);

{
  "type": "module"
}

Step 3: Test Your Installation

Create a test file (test-toon.js):

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

// Sample data
const testData = {
  users: [
    { id: 1, name: 'Alice', role: 'admin' },
    { id: 2, name: 'Bob', role: 'user' }
  ]
};

// Test encoding
console.log('Original JSON:');
console.log(JSON.stringify(testData, null, 2));

console.log('\nEncoded TOON:');
const encoded = encode(testData);
console.log(encoded);

// Test decoding
console.log('\nDecoded back to JSON:');
const decoded = decode(encoded);
console.log(JSON.stringify(decoded, null, 2));

Run the test:

node test-toon.js

Expected output:

Original JSON:
{
  "users": [
    { "id": 1, "name": "Alice", "role": "admin" },
    { "id": 2, "name": "Bob", "role": "user" }
  ]
}

Encoded TOON:
users[2]{id,name,role}:
  1,Alice,admin
  2,Bob,user

Decoded back to JSON:
{
  "users": [
    { "id": 1, "name": "Alice", "role": "admin" },
    { "id": 2, "name": "Bob", "role": "user" }
  ]
}

Core TOON Implementation Patterns

Pattern 1: Basic JSON to TOON Conversion

The simplest use case: converting a JSON object to TOON format.

import { encode } from '@toon-format/toon';

// Example: E-commerce products
const products = {
  items: [
    { sku: 'PROD001', name: 'Laptop', price: 999, stock: 45 },
    { sku: 'PROD002', name: 'Mouse', price: 29, stock: 150 },
    { sku: 'PROD003', name: 'Keyboard', price: 79, stock: 87 }
  ]
};

const toonOutput = encode(products);
console.log(toonOutput);

Output:

items[3]{sku,name,price,stock}:
  PROD001,Laptop,999,45
  PROD002,Mouse,29,150
  PROD003,Keyboard,79,87

Use case: Sending product catalogs to LLMs for recommendations, price comparisons, or inventory analysis.

Pattern 2: Complex Objects with Nested Data

When you have nested objects or mixed data structures:

import { encode } from '@toon-format/toon';

const complexData = {
  store: {
    name: "TechMart",
    location: "Downtown",
    sales: [
      { date: "2025-01-01", revenue: 2500, units: 45 },
      { date: "2025-01-02", revenue: 3100, units: 52 },
      { date: "2025-01-03", revenue: 2800, units: 48 }
    ]
  }
};

const toon = encode(complexData);
console.log(toon);

Output:

store:
  name: TechMart
  location: Downtown
  sales[3]{date,revenue,units}:
    2025-01-01,2500,45
    2025-01-02,3100,52
    2025-01-03,2800,48

Key behavior: TOON automatically detects tabular arrays (uniform objects) and encodes them efficiently, while preserving nested structures.

Pattern 3: Round-Trip Conversion (JSON ↔ TOON)

Encoding and decoding data while preserving structure:

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

// Original JavaScript object
const original = {
  users: [
    { id: 1, email: "alice@example.com", verified: true },
    { id: 2, email: "bob@example.com", verified: false }
  ]
};

// Encode to TOON
const toonString = encode(original);
console.log('TOON format:', toonString);

// Decode back to JavaScript object
const restored = decode(toonString);
console.log('Restored:', JSON.stringify(restored, null, 2));

// Verify they're identical
console.log('Identical?', JSON.stringify(original) === JSON.stringify(restored));

Use case: Store data in TOON format in databases, then convert back to JSON for client responses—reducing storage and transmission costs.

Advanced Configuration Options

Option 1: Custom Delimiters

By default, TOON uses commas. You can customize this for different use cases:

Tab-delimited (often more token-efficient):

import { encode } from '@toon-format/toon';

const data = {
  metrics: [
    { date: "2025-01-01", views: 1200, clicks: 45, conversions: 8 },
    { date: "2025-01-02", views: 1450, clicks: 52, conversions: 9 }
  ]
};

const toonTab = encode(data, { delimiter: '\t' });
console.log(toonTab);

When to use each delimiter:

• Comma (`,`): Default, most compatible
• Tab (`\t`): Often saves 5-10% more tokens than commas
• Pipe (`|`): When data contains commas naturally

Option 2: Indentation Control

Control spacing for readability vs. token efficiency:

import { encode } from '@toon-format/toon';

const data = {
  users: [
    { id: 1, name: 'Alice' },
    { id: 2, name: 'Bob' }
  ]
};

// 2-space indentation (default)
const toon2 = encode(data, { indent: 2 });

// 1-space indentation (more compact)
const toon1 = encode(data, { indent: 1 });

// 4-space indentation (more readable)
const toon4 = encode(data, { indent: 4 });

Option 3: Combining Options

import { encode } from '@toon-format/toon';

// Maximum token efficiency: tab delimiter, 1-space indent
const optimized = encode(analyticsData, { 
  delimiter: '\t', 
  indent: 1 
});

console.log('Optimized for LLM APIs:', optimized);

Express.js Integration: Building TOON-Optimized APIs

Basic Setup: Express Server with TOON Endpoints

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

const app = express();
app.use(express.json());

// Middleware to add TOON response capability
app.use((req, res, next) => {
  const originalJson = res.json.bind(res);
  
  res.json = function(data) {
    // If client requests TOON format
    if (req.query.format === 'toon' || req.headers['accept-format'] === 'toon') {
      const toonData = encode(data, { indent: 1 });
      res.setHeader('Content-Type', 'text/plain; charset=utf-8');
      res.send(toonData);
    } else {
      originalJson(data);
    }
  };
  
  next();
});

// Example endpoint
app.get('/api/users', (req, res) => {
  const users = [
    { id: 1, name: 'Alice', email: 'alice@example.com', active: true },
    { id: 2, name: 'Bob', email: 'bob@example.com', active: true }
  ];
  
  res.json({ users });
});

app.listen(3000, () => console.log('Server on port 3000'));

Usage:

# Get response in JSON (default)
curl http://localhost:3000/api/users

# Get response in TOON format
curl "http://localhost:3000/api/users?format=toon"

# Or using header
curl -H "Accept-Format: toon" http://localhost:3000/api/users

Advanced: LLM-Optimized API Endpoint

Create an endpoint specifically for LLM integration:

import express from 'express';
import { encode } from '@toon-format/toon';

const app = express();
app.use(express.json());

// Endpoint to get data in TOON format for LLM APIs
app.post('/api/llm/data', async (req, res) => {
  const { query } = req.body;
  
  try {
    // Fetch data from database/API
    const data = await fetchDataFromSource(query);
    
    // Encode to TOON for maximum efficiency
    const toonData = encode(data, { 
      delimiter: '\t', 
      indent: 1 
    });
    
    // Return with metadata
    res.json({
      format: 'toon',
      data: toonData,
      originalTokens: Math.ceil(JSON.stringify(data).length / 4),
      optimizedTokens: Math.ceil(toonData.length / 4),
      savings: Math.round((1 - toonData.length / JSON.stringify(data).length) * 100)
    });
    
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

Real-World Implementation: Analytics Dashboard

A complete example sending analytics data to Claude AI:

import { encode } from '@toon-format/toon';

// 1. Fetch analytics data
async function getAnalyticsData(dateRange) {
  const analyticsData = {
    period: dateRange,
    dailyMetrics: [
      { date: '2025-01-01', sessions: 2450, users: 1203, pageViews: 8921 },
      { date: '2025-01-02', sessions: 2678, users: 1345, pageViews: 9801 },
      { date: '2025-01-03', sessions: 2334, users: 1098, pageViews: 8234 }
      // ... more days
    ],
    topPages: [
      { path: '/home', views: 45231, avgTime: '2:34' },
      { path: '/products', views: 38921, avgTime: '3:12' }
    ]
  };
  
  return analyticsData;
}

// 2. Prepare TOON format
async function prepareAnalyticsForLLM() {
  const data = await getAnalyticsData('2025-01-01 to 2025-01-30');
  
  // Encode with maximum efficiency
  const toonData = encode(data, { delimiter: '\t', indent: 1 });
  
  console.log('TOON-Formatted Analytics:', toonData);
  return toonData;
}

// 3. Send to Claude for analysis
async function analyzeWithClaude() {
  const analyticsData = await prepareAnalyticsForLLM();
  
  const response = await fetch('https://api.anthropic.com/v1/messages', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': process.env.CLAUDE_API_KEY,
      'anthropic-version': '2023-06-01'
    },
    body: JSON.stringify({
      model: 'claude-3-5-sonnet-20241022',
      max_tokens: 1024,
      system: `You are an expert data analyst. Analyze the provided analytics 
data in TOON format and provide insights on trends and patterns.`,
      messages: [{
        role: 'user',
        content: `Analyze this analytics data:\n\n${analyticsData}`
      }]
    })
  });
  
  const result = await response.json();
  console.log('Analysis Results:', result.content[0].text);
}

Performance Benchmarks & Optimization Tips

Token Efficiency Benchmarks

Optimization Techniques

1. Use tab delimiter for maximum savings:

const optimized = encode(data, { delimiter: '\t' });
// Typically saves additional 5-10% vs comma delimiter

2. Ensure data uniformity for tabular format:

// ✅ Uniform (TOON tabular format - 50-60% savings)
const uniform = {
  items: [
    { id: 1, name: 'Item A', price: 29.99 },
    { id: 2, name: 'Item B', price: 39.99 },
    { id: 3, name: 'Item C', price: 49.99 }
  ]
};

// ❌ Non-uniform (TOON list format - 10-20% savings)
const nonUniform = {
  items: [
    { id: 1, name: 'Item A', price: 29.99 },
    { id: 2, name: 'Item B' }, // missing price
    { id: 3, name: 'Item C', price: 49.99, discount: '10%' } // extra field
  ]
};

3. Use 1-space indentation for LLM APIs:

const compact = encode(data, { indent: 1 });
// Saves ~10% more tokens from whitespace

Error Handling & Edge Cases

Handling Encoding Errors

import { encode } from '@toon-format/toon';

function safeEncode(data, options = {}) {
  try {
    if (!data) {
      throw new Error('Data is null or undefined');
    }
    
    if (typeof data !== 'object') {
      throw new Error('Data must be an object or array');
    }
    
    return encode(data, options);
    
  } catch (error) {
    console.error('TOON encoding failed:', error.message);
    
    // Fallback to JSON
    console.warn('Falling back to JSON format');
    return JSON.stringify(data);
  }
}

// Usage
const result = safeEncode({ users: [...] });

Handling Decoding Errors

import { decode } from '@toon-format/toon';

function safeDecode(toonString) {
  try {
    if (!toonString || typeof toonString !== 'string') {
      throw new Error('Invalid TOON input');
    }
    
    return decode(toonString);
    
  } catch (error) {
    console.error('TOON decoding failed:', error.message);
    
    // Try parsing as JSON fallback
    try {
      return JSON.parse(toonString);
    } catch {
      console.error('Could not parse as JSON either');
      return null;
    }
  }
}

Data Type Support

TOON supports primitives (strings, numbers, booleans, null) and structure (objects, arrays). Special handling:

Frequently Asked Questions

Q1: Should I always use TOON instead of JSON?

A: No. Use TOON when:

• ✅ Sending data to LLMs (token cost matters)
• ✅ Data is uniform arrays (100+ similar objects)
• ✅ You need token efficiency

Use JSON when:

• ✅ Building REST APIs (client compatibility)
• ✅ Data is deeply nested
• ✅ Objects have varying fields

Q2: Can I use TOON with TypeScript?

A: Yes! The @toon-format/toon package includes TypeScript definitions:

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

interface User {
  id: number;
  name: string;
  email: string;
}

const users: User[] = [
  { id: 1, name: 'Alice', email: 'alice@example.com' }
];

const toon: string = encode({ users });
const decoded: any = decode(toon);

Q3: What's the performance impact of using TOON?

A: Minimal:

• Encoding: ~120µs (negligible)
• Decoding: ~150µs (negligible)
• Token savings: 30-60% (major)

The token cost savings vastly outweigh parsing overhead.

Q4: How do I handle errors in production?

A: Use the error handling pattern with fallback to JSON:

function encodeWithFallback(data) {
  try {
    return { format: 'toon', data: encode(data) };
  } catch (error) {
    console.error('TOON encoding failed, using JSON:', error);
    return { format: 'json', data: JSON.stringify(data) };
  }
}

Conclusion: Building TOON-Optimized JavaScript Applications

By integrating TOON format into your JavaScript applications, you can:

• ✅ Reduce LLM API costs by 30-60% — Direct savings on your monthly bill
• ✅ Improve LLM accuracy by 4-7% — Better comprehension with explicit structure
• ✅ Speed up inference — Fewer tokens = faster responses
• ✅ Build scalable AI features — Cost-efficient integration with Claude, GPT-4, Gemini
• ✅ Maintain compatibility — Round-trip conversion between JSON and TOON

Next Steps

1. Install the library: npm install @toon-format/toon
2. Try the basics: Run the test file from Step 3
3. Integrate into Express: Add TOON endpoints to your API
4. Measure impact: Compare JSON vs TOON token usage
5. Scale gradually: Start with highest-volume LLM integrations

Related Articles

• What is TOON Format? - Complete introduction to TOON
• TOON vs JSON - Detailed format comparison
• How to Convert JSON to TOON - Step-by-step tutorial
• TOON Format for Python - Python implementation guide
• TOON for ChatGPT - Optimize ChatGPT API costs
• TOON for Claude API - Anthropic LLM optimization
• LLM Token Optimization - Complete optimization guide