Compare and convert JSON to TOON format with token efficiency analysis – includes CLI, API, and Web UI server.
npm install json-toon-parserbash
npm install -g json-toon-parser
`
Project (Programmatic API):
`bash
npm install json-toon-parser
`
Quick Start – Web UI
Start the local server:
`bash
json-toon serve
`
Browse to: http://localhost:3000 → paste JSON → convert → copy/download TOON.
CLI Usage
`bash
Start web UI server (recommended for easy usage)
json-toon serve
Or with custom port:
json-toon serve --port 8080
Compare JSON with TOON format
json-toon compare data.json
Convert JSON to TOON
json-toon convert data.json output.toon
Update JSON and generate comparison
json-toon update data.json
`
Programmatic Usage
`javascript
import { compare, convertFile, jsonToToon } from 'json-toon-parser';
// Compare JSON data
const result = compare({ name: "John", age: 30 }, { saveToFile: true });
console.log(result);
// Output: { jsonTokens: 15, toonTokens: 8, savings: 7, savingsPercentage: 46.67 }
// Convert file
const outputPath = convertFile('input.json', 'output.toon');
console.log(Saved to: ${outputPath});
// Convert JSON to TOON string
const toonString = jsonToToon({ hello: "world" });
`
Features
- 🌐 Web UI – Responsive, modern conversion dashboard
- ✅ Direct JSON → TOON conversion (string or file)
- 📊 Token efficiency metrics (JSON vs TOON counts, savings %)
- 💾 Timestamped output file generation
- 🔧 CLI commands: serve, compare, convert, update
- 📦 Programmatic API with types & tree-shakeable exports
- ⚡ Real-time stats + sample datasets in UI
- 🧪 GPT-style token counting via gpt-3-encoder
API (Summary)
json-toon-parser



================================================================================
🚀 json-toon-parser — JSON → TOON converter, token optimizer, and developer toolkit
Convert verbose JSON into compact TOON, reduce LLM token usage, and measure savings.
Perfect for teams and engineers integrating large structured payloads into ChatGPT/OpenAI/Claude prompts or storage pipelines.
Official NPM package: https://www.npmjs.com/package/json-toon-parser
Documentation: docs/API.md
================================================================================
Quick Install
Global (CLI + Web UI):
`bash
npm install -g json-toon-parser
`
Programmatic (project):
`bash
npm install json-toon-parser
`
Verify:
`bash
json-toon --version
json-toon serve
`
================================================================================
Why TOON? — The Value Proposition
TOON is a compact, human-friendly serialization optimized for token-efficient LLM prompts. It removes syntactic noise (quotes, braces, commas), reduces repeated keys, and uses concise array and nesting notation — which directly translates to lower API costs and faster transmission.
- Reduce per-request token counts by 40–70% (depends on structure)
- Keep payloads human-readable and reversible via the TOON library
- Ideal for prompts, telemetry, logs, and mobile/edge transfers
================================================================================
Features
- CLI: serve, compare, convert, update
- Web UI: interactive editor, samples, copy & download
- Programmatic API (TypeScript types included)
- Token analysis using gpt-3-encoder for GPT-style counts
- Save TOON output with timestamped filenames
================================================================================
Usage Examples
CLI
`bash
Start web UI
json-toon serve
Compare & save TOON
json-toon compare data/input.json --save
Convert file
json-toon convert data/input.json output.toon
Update JSON and produce comparison
json-toon update data/input.json
`
Programmatic
`ts
import { compare, jsonToToon } from 'json-toon-parser';
const data = { users: [{ id: 1, name: 'Alice' }] };
const toon = jsonToToon(data);
const result = compare(data, { saveToFile: false });
console.log(result.toonOutput);
`
================================================================================
Example Comparison
Use this example to demonstrate typical savings — include it in docs, blog posts, or README highlights:
`
============================================================
COMPARISON RESULTS
============================================================
JSON Tokens: 24890
TOON Tokens: 10204
Token Savings: 14686
Efficiency: 59.00% reduction
Output File: output/data_DateTime.toon
============================================================
`
================================================================================
When TOON Is Most Effective
- Nested JSON with many structural characters
- Large arrays of similar objects
- Repetitive keys repeated across objects
- Prompts that include large contexts for LLMs
================================================================================
Performance Notes
Token counting is approximated with gpt-3-encoder. Results may vary slightly by tokenizers used by different LLM providers, but the relative savings are consistent.
================================================================================
Links & Resources
- NPM: https://www.npmjs.com/package/json-toon-parser
- TOON format: https://github.com/bhushan020/json-toon-parser
- API docs: docs/API.md
================================================================================
Contributing
See CONTRIBUTING.md` to get started. We welcome PRs, issues, and ideas.