Skip to main content

​
Installation

Install the TOON SDK for TypeScript/JavaScript: 
npm install @toon-format/toon
Package: @toon-format/toon v2.1.0 or later
Homepage: toonformat.dev
GitHub: github.com/toon-format/toon

​
Your First Encoding

Encode JavaScript objects to TOON format using the encode() function: 
import { encode } from '@toon-format/toon'

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

console.log(encode(data))
Output: 
users[2]{id,name,role}:
  1,Alice,admin
  2,Bob,user
Notice how TOON declares the array length [2] and field names {id,name,role} once, then streams row values. This is the key to TOON’s token efficiency.

​
Your First Decoding

Decode TOON strings back to JavaScript objects using the decode() function: 
import { decode } from '@toon-format/toon'

const toon = `users[2]{id,name,role}:
  1,Alice,admin
  2,Bob,user`

const result = decode(toon)
console.log(result)
Output: 
{
  "users": [
    { "id": 1, "name": "Alice", "role": "admin" },
    { "id": 2, "name": "Bob", "role": "user" }
  ]
}
TOON provides 100% lossless, deterministic round-trips between JSON and TOON. No data is lost in conversion.

​
Working with Real Data

Let’s encode a more realistic dataset - employee records: 
import { encode } from '@toon-format/toon'

const employees = {
  company: 'Acme Corp',
  department: 'Engineering',
  employees: [
    { id: 101, name: 'Alice Johnson', salary: 95000, active: true },
    { id: 102, name: 'Bob Smith', salary: 87000, active: true },
    { id: 103, name: 'Carol White', salary: 92000, active: false }
  ]
}

console.log(encode(employees))
Output: 
company: Acme Corp
department: Engineering
employees[3]{id,name,salary,active}:
  101,Alice Johnson,95000,true
  102,Bob Smith,87000,true
  103,Carol White,92000,false
Token Comparison:
  • JSON (formatted): ~180 tokens
  • TOON: ~95 tokens
  • Savings: ~47%

​
Encoding Options

Customize encoding with options: 
import { encode } from '@toon-format/toon'

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

// Use 4 spaces for indentation (default is 2)
const toon = encode(data, { indent: 4 })
See Encode Options for all available configuration options.

​
Streaming Large Datasets

For large datasets, use encodeLines() to stream output line by line without building the full string in memory: 
import { encodeLines } from '@toon-format/toon'

const largeData = await fetchThousandsOfRecords()

// Memory-efficient streaming
for (const line of encodeLines(largeData)) {
  process.stdout.write(`${line}\n`)
}
When to use streaming:
  • Datasets with thousands of records
  • Writing to files or HTTP responses
  • Memory-constrained environments
  • Real-time data processing
For streaming decode, see decodeFromLines(), decodeStreamSync(), and decodeStream().

​
Using the CLI

For quick conversions without writing code, use the TOON CLI:
1

No installation needed

Use npx to run the CLI instantly:
# Convert JSON to TOON
npx @toon-format/cli input.json -o output.toon

# Decode TOON to JSON
npx @toon-format/cli data.toon -o output.json
2

Pipe from stdin

The CLI auto-detects format and supports pipes:
# Pipe JSON directly
echo '{"name": "Ada", "role": "dev"}' | npx @toon-format/cli

# Chain with other tools
curl https://api.example.com/data | npx @toon-format/cli
3

Analyze token savings

Use --stats to compare token counts:
npx @toon-format/cli data.json --stats
# TOON: 1,234 tokens
# JSON: 2,456 tokens  
# Savings: 49.8%
See the CLI Guide for all options and examples.

​
Working with LLMs

TOON works best when you show the format instead of describing it. The structure is self-documenting: 
import { encode } from '@toon-format/toon'
import Anthropic from '@anthropic-ai/sdk'

const client = new Anthropic()

const employees = [
  { id: 1, name: 'Alice', dept: 'Eng', salary: 95000 },
  { id: 2, name: 'Bob', dept: 'Sales', salary: 87000 },
  // ... 100 more employees
]

// Encode data as TOON
const toonData = encode({ employees })

const response = await client.messages.create({
  model: 'claude-4.5-sonnet',
  max_tokens: 1024,
  messages: [{
    role: 'user',
    content: `Here is employee data in TOON format:

\`\`\`toon
${toonData}
\`\`\`

How many employees in Engineering have salary > $90,000?`
  }]
})
Pro tip: Wrap TOON in ```toon code blocks for input. For generation tasks, show the expected header template and use tab delimiters for better efficiency.
See the LLM Integration Guide for detailed strategies.

​
Transforming Data with Replacer

Use the replacer function to filter or transform values during encoding: 
import { encode } from '@toon-format/toon'

const user = {
  name: 'Alice',
  email: '[email protected]',
  password: 'secret123',
  apiKey: 'sk-abc123'
}

const safe = encode(user, {
  replacer: (key, value) => {
    // Remove sensitive fields
    if (key === 'password' || key === 'apiKey') {
      return undefined
    }
    return value
  }
})

// Output:
// name: Alice
// email: [email protected]
The replacer function is similar to JSON.stringify’s replacer but includes path tracking. See the Replacer Function Guide for more examples.

​
Next Steps

Now that you’ve learned the basics, explore these topics:

Format Overview

Learn the complete TOON syntax and structure

Encoding Guide

Master all encoding options and patterns

Streaming

Handle large datasets efficiently

API Reference

Explore all functions and options

​
Interactive Playground

Experiment with TOON in your browser:

​
Editor Support

Install syntax highlighting and validation for your editor:

VS Code

Install the TOON Language Support extension:
code --install-extension vishalraut.vscode-toon

Neovim

Install toon.nvim plugin

Tree-sitter

Use tree-sitter-toon for any editor with Tree-sitter support (Helix, Emacs, Zed)

Other Editors

Use YAML syntax highlighting as a close approximation
Need help? Check the GitHub repository or file an issue.

Build docs developers (and LLMs) love

Get started for freeTalk to us