json-toon

High-performance JSON to TOON and TOON to JSON converter with zero dependencies.

What is TOON?

TOON (Token-Oriented Object Notation) is a compact, human-readable data serialization format optimized for LLM context windows. It achieves 30-60% token reduction compared to JSON by:

• Declaring array fields once instead of repeating them
• Using indentation instead of braces
• Combining YAML-like structure with CSV-style tabular arrays

Features

• 🚀 Zero dependencies - Minimal footprint
• ⚡ High performance - Optimized for speed and memory efficiency
• 🔄 Lossless conversion - Perfect round-trip JSON ↔ TOON
• 📊 Token efficient - 30-60% smaller than JSON for uniform arrays
• 🎯 TypeScript support - Full type definitions included
• 🧪 Well tested - Comprehensive test suite

Installation

npm install json-toon

pnpm add json-toon

yarn add json-toon

Quick Start

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

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

const toon = encode(data);
console.log(toon);
// Output:
// users[2]{id,name,role}:
// 1,Alice,admin
// 2,Bob,user

// TOON to JSON
const json = decode(toon);
console.log(json);
// Output: { users: [ { id: 1, name: 'Alice', role: 'admin' }, ... ] }

API Reference

encode(data, options?)

Converts JSON data to TOON format.

Parameters:

• data: any - The JSON data to encode
• options?: EncodeOptions - Optional encoding options
  • indent?: string - Indentation string (default: ' ' - 2 spaces)
  • delimiter?: string - Delimiter for tabular arrays (default: ',')
  • useTabs?: boolean - Use tabs instead of commas for better token efficiency (default: false)

Returns: string - The TOON formatted string

Example:

const toon = encode(data, { 
  indent: '    ',  // 4 spaces
  useTabs: true    // Use tabs for maximum token efficiency
});

decode(toon, options?)

Converts TOON format to JSON data.

Parameters:

• toon: string - The TOON formatted string to decode
• options?: DecodeOptions - Optional decoding options
  • strict?: boolean - Enable strict parsing mode (default: true)
  • inferTypes?: boolean - Automatically infer types for primitive values (default: true)

Returns: any - The decoded JSON data

Example:

const json = decode(toon, { 
  strict: false,      // Don't throw on minor format issues
  inferTypes: false   // Keep all values as strings
});

Examples

Simple Objects

const data = {
  name: 'Alice',
  age: 30,
  active: true
};

const toon = encode(data);
// name: Alice
// age: 30
// active: true

Nested Objects

const data = {
  user: {
    profile: {
      name: 'Alice',
      email: '[email protected]'
    }
  }
};

const toon = encode(data);
// user:
//   profile:
//     name: Alice
//     email: [email protected]

Uniform Arrays (Tabular Format)

const data = {
  products: [
    { id: 1, name: 'Laptop', price: 999.99, inStock: true },
    { id: 2, name: 'Mouse', price: 29.99, inStock: false },
    { id: 3, name: 'Keyboard', price: 79.99, inStock: true }
  ]
};

const toon = encode(data);
// products[3]{id,name,price,inStock}:
// 1,Laptop,999.99,true
// 2,Mouse,29.99,false
// 3,Keyboard,79.99,true

Complex Structures

const data = {
  metadata: {
    version: '1.0.0',
    timestamp: '2025-11-20T00:00:00Z'
  },
  users: [
    { id: 1, name: 'Alice', role: 'admin' },
    { id: 2, name: 'Bob', role: 'user' }
  ],
  config: {
    debug: false,
    timeout: 5000
  }
};

const toon = encode(data);
// metadata:
//   version: 1.0.0
//   timestamp: 2025-11-20T00:00:00Z
// users[2]{id,name,role}:
// 1,Alice,admin
// 2,Bob,user
// config:
//   debug: false
//   timeout: 5000

Performance

The package is optimized for both speed and memory efficiency:

• Encoding: ~1000 items in <100ms
• Decoding: ~1000 items in <100ms
• Token savings: 30-60% compared to JSON for uniform arrays
• Memory: Efficient for large datasets (tested with 10,000+ items)

Run benchmarks:

npm run bench

Token Efficiency Comparison

For the same data, TOON uses significantly fewer tokens than JSON:

const data = {
  users: [
    { id: 1, name: 'Alice', role: 'admin', active: true },
    { id: 2, name: 'Bob', role: 'user', active: false },
    { id: 3, name: 'Charlie', role: 'user', active: true }
  ]
};

// JSON: 169 characters
// TOON: ~120 characters
// Savings: ~29%

The savings increase with larger uniform arrays!

⚡ Performance & Comparison with official TOON

json-toon is built for speed and simplicity. Compared to the official TOON implementation, this package is significantly lighter and faster for common use cases.

| Feature | json-toon | Official TOON | |---------|-----------|---------------| | Time Complexity | O(n) | O(n log n) | | Space Complexity | O(n) | O(n + d + k) | | Encoding Speed | ~3.6ms / 1k items | ~6-8ms / 1k items | | Memory Usage | Low (~2n) | Medium (~4n) | | Code Size | ~410 lines | ~1,800+ lines | | Spec Compliance | ~80% (Common cases) | 100% |

Why is it faster?

1. Direct Array Manipulation: We avoid class-based overhead and abstraction layers.
2. Single-Pass Processing: Data is processed in a single pass without complex pre-validation steps.
3. Focused Feature Set: We skip expensive operations like key folding and dotted key expansion, which are rarely needed for standard API payloads.

Use json-toon if: You need raw speed, low memory usage, and are working with standard data structures (uniform arrays, nested objects).

Use official TOON if: You need 100% spec compliance for edge cases, complex key folding, or strict validation.

Use Cases

TOON is ideal for:

• 🤖 LLM prompts - Reduce token usage and API costs
• 📊 Tabular data - Efficient representation of uniform arrays
• 🔄 Data interchange - Human-readable alternative to JSON
• 📝 Configuration files - More compact than JSON, more structured than YAML

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run benchmarks
npm run bench

# Build
npm run build

# Type check
npm run typecheck

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © abdumajid

Related

• TOON Specification
• Official TOON Repository
• TOON Format Documentation