json2toon-converter

Convert between JSON and TOON (Token-Oriented Object Notation) formats — lossless, bidirectional, and LLM-friendly.

TOON is a compact, human-readable encoding of the JSON data model that minimizes tokens for LLM prompts. This package wraps the official @toon-format/toon library and provides two simple functions.

Install

npm install json2toon-converter

Usage

import { jsonToToon, toonToJson } from 'json2toon-converter';

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

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

// Also accepts a JSON string directly:
jsonToToon('{"name":"Ada","role":"dev"}');
// name: Ada
// role: dev

// ── TOON → JSON ────────────────────────────────
const toon = `users[2]{id,name,role}:
1,Alice,admin
2,Bob,user`;

console.log(toonToJson(toon));
// {
//   "users": [
//     { "id": 1, "name": "Alice", "role": "admin" },
//     { "id": 2, "name": "Bob",   "role": "user"  }
//   ]
// }

// Get a raw JS object instead of a JSON string:
toonToJson(toon, { raw: true });
// => { users: [ { id: 1, name: 'Alice', role: 'admin' }, ... ] }

API

jsonToToon(input, options?)

Converts a JSON string or JS value to a TOON string.

| Parameter | Type | Default | Description | |---|---|---|---| | input | string \| object \| any | — | A JSON string or any JSON-serializable value | | options.indent | number | 2 | TOON indentation width | | options.delimiter | string | ',' | Delimiter: ',', '\t', or '\|' | | options.keyFolding | string | 'off' | 'off' | 'safe' | 'force' |

Returns: string — TOON-formatted output.

toonToJson(input, options?)

Converts a TOON string to JSON.

| Parameter | Type | Default | Description | |---|---|---|---| | input | string | — | A TOON-formatted string | | options.raw | boolean | false | Return parsed JS value instead of JSON string | | options.jsonIndent | number | 2 | JSON.stringify indentation | | options.strict | boolean | true | Strict TOON parsing | | options.indent | number | 2 | TOON indentation width for decoding | | options.expandPaths | string | 'off' | 'off' | 'safe' | 'force' |

Returns: string (JSON) or the parsed JS value if raw: true.

What is TOON?

TOON is a compact, human-readable encoding of JSON designed for LLM prompts. It uses YAML-like indentation for objects and CSV-style tabular rows for uniform arrays, achieving ~40% fewer tokens than JSON while maintaining lossless round-trip fidelity.

Contributing

We welcome contributions! Please see our Contributing Guide and Code of Conduct for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.