Easily read/write TOON (Token-Oriented Object Notation) files in Node.js.
TOON is a compact, human-readable format designed for LLM prompts that reduces token usage by 30-60% compared to JSON while maintaining readability. This library makes it as easy to work with .toon files as it is to work with .json files.
Like jsonfile, but for TOON format.
npm install toonfileconst toonfile = require('toonfile') // Read TOON file const config = await toonfile.readFile('./config.toon') // Write TOON file const data = { name: 'Alice', scores: [95, 87, 92] } await toonfile.writeFile('./output.toon', data)Read and parse a TOON file.
Options:
encoding(string, default:'utf8'): File encodingthrows(boolean, default:true): Throw error on parse failure. Iffalse, returnsnullfor invalid files.reviver(function): Transform function for parsed valuesfs(object): Custom fs module for testing
Examples:
// With callback toonfile.readFile('config.toon', (err, data) => { if (err) console.error(err) console.log(data) }) // With promise const data = await toonfile.readFile('config.toon') // With async/await async function loadConfig () { const config = await toonfile.readFile('config.toon') return config } // Silent error handling const data = await toonfile.readFile('config.toon', { throws: false }) if (!data) console.log('File not found or invalid')Synchronous version of readFile.
const toonfile = require('toonfile') const config = toonfile.readFileSync('./config.toon') console.log(config)Stringify object and write to TOON file.
Options:
encoding(string, default:'utf8'): File encodingindentSize(number, default:2): Spaces per indent leveldelimiter(string, default:','): Delimiter for arrays:',','\t', or'|'EOL(string, default:'\n'): End-of-line characterfinalEOL(boolean, default:true): Include EOL at end of filefs(object): Custom fs module for testing
Examples:
const data = { company: 'TechCorp', employees: [ { id: 1, name: 'Alice', role: 'Engineer' }, { id: 2, name: 'Bob', role: 'Designer' } ] } // Basic write await toonfile.writeFile('data.toon', data) // With options await toonfile.writeFile('data.toon', data, { indentSize: 4, delimiter: '|', EOL: '\r\n' }) // Callback style toonfile.writeFile('data.toon', data, (err) => { if (err) console.error(err) console.log('Write complete!') })Formatting with spaces:
await toonfile.writeFile('data.toon', obj, { indentSize: 4 })Overriding EOL:
await toonfile.writeFile('data.toon', obj, { EOL: '\r\n' })Disabling the EOL at the end of file:
await toonfile.writeFile('data.toon', obj, { finalEOL: false })Appending to an existing file:
You can use the fs.writeFile option { flag: 'a' } to achieve this.
await toonfile.writeFile('data.toon', obj, { flag: 'a' })Synchronous version of writeFile.
const toonfile = require('toonfile') toonfile.writeFileSync('./data.toon', { name: 'Bob', age: 25 })Parse a TOON string to JavaScript object.
const toon = 'name: Alice\nage: 30' const obj = toonfile.parse(toon) // → { name: 'Alice', age: 30 }Convert JavaScript object to TOON string.
const obj = { name: 'Bob', scores: [95, 87, 92] } const toon = toonfile.stringify(obj) // → 'name: Bob\nscores[3]: 95,87,92'JavaScript:
{ name: 'Alice', age: 30, city: 'Boston' }TOON:
name: Alice age: 30 city: Boston JavaScript:
{ person: { name: 'Alice', address: { city: 'Boston', zip: '02101' } } }TOON:
person: name: Alice address: city: Boston zip: 02101 JavaScript:
{ scores: [95, 87, 92] }TOON:
scores[3]: 95,87,92 JavaScript:
{ company: 'TechCorp', founded: 2020, active: true, employees: ['Alice', 'Bob', 'Carol'], metadata: { location: 'Boston', remote: true } }TOON:
company: TechCorp founded: 2020 active: true employees[3]: Alice,Bob,Carol metadata: location: Boston remote: true JSON (124 characters):
{ "name": "Alice", "age": 30, "scores": [95, 87, 92], "address": { "city": "Boston" } }TOON (73 characters - 41% reduction):
name: Alice age: 30 scores[3]: 95,87,92 address: city: Boston TOON (Token-Oriented Object Notation) is a compact, human-readable encoding designed specifically for LLM prompts. It provides:
- 30-60% token reduction compared to JSON
- Human-readable syntax similar to YAML
- Schema-aware structure with explicit array lengths
- Lossless serialization of the JSON data model
Learn more at toon-format.org
- jsonfile - The inspiration for this library
- TOON Specification - Official TOON format spec
- TOON TypeScript SDK - Official TypeScript implementation
https://github.com/ideas2codedev/node-toonfile
MIT
Contributions are welcome! Please feel free to submit a Pull Request at https://github.com/ideas2codedev/node-toonfile.