Quickstart

Installation

Install the TOON SDK for TypeScript/JavaScript:

npm install @toon-format/toon

pnpm add @toon-format/toon

yarn add @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 })

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

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

// Use tabs instead of commas (even more efficient!)
const toon = encode(data, { delimiter: '\t' })
// users[1]{id\tname}:
//   1\tAlice

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

const data = {
  api: {
    config: {
      timeout: 5000
    }
  }
}

// Collapse single-key chains into dotted paths
const toon = encode(data, { keyFolding: 'safe' })
// api.config.timeout: 5000

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:

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

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

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: 'alice@example.com',
  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: alice@example.com

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

const data = {
  status: 'active',
  category: 'premium',
  count: 42
}

const transformed = encode(data, {
  replacer: (key, value) => {
    // Uppercase all strings
    if (typeof value === 'string') {
      return value.toUpperCase()
    }
    return value
  }
})

// Output:
// status: ACTIVE
// category: PREMIUM
// count: 42

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

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

const withMeta = encode(data, {
  replacer: (key, value, path) => {
    // Add timestamp to root object
    if (path.length === 0 && typeof value === 'object' && value !== null) {
      return {
        _timestamp: Date.now(),
        _version: '1.0',
        ...value
      }
    }
    return value
  }
})

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:

Official TOON Playground - Real-time conversion and token comparison
Format Tokenization Explorer
TOON Tools

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.

Get Started

Core Concepts

Usage Guides

Advanced

Installation

Your First Encoding

Your First Decoding

Working with Real Data

Encoding Options

Streaming Large Datasets

Using the CLI

Working with LLMs

Transforming Data with Replacer

Next Steps

Format Overview

Encoding Guide

Streaming

API Reference

Interactive Playground

Editor Support

VS Code

Neovim

Tree-sitter

Other Editors

​Installation

​Your First Encoding

​Your First Decoding

​Working with Real Data

​Encoding Options

​Streaming Large Datasets

​Using the CLI

​Working with LLMs

​Transforming Data with Replacer

​Next Steps

Format Overview

Encoding Guide

Streaming

API Reference

​Interactive Playground

​Editor Support

VS Code

Neovim

Tree-sitter

Other Editors

Installation

Your First Encoding

Your First Decoding

Working with Real Data

Encoding Options

Streaming Large Datasets

Using the CLI

Working with LLMs

Transforming Data with Replacer

Next Steps

Interactive Playground

Editor Support