CTON (Compact Token-Oriented Notation) is a token-efficient, JSON-compatible wire format built for LLM prompts. It keeps structure explicit (objects, arrays, table arrays) while removing syntactic noise, so prompts are shorter and outputs are easier to validate. CTON is deterministic and round-trippable, making it safe for LLM workflows.
CTON is designed to be the reference language for LLM data exchange: short, deterministic, schema-aware.
npm install cton-jsconst Cton = require('cton-js');
const payload = {
user: { id: 42, name: "Ada" },
tags: ["llm", "compact"],
events: [
{ id: 1, action: "login" },
{ id: 2, action: "upload" }
]
};
const cton = Cton.dump(payload);
// => user(id=42,name=Ada)
// => tags[2]=llm,compact
// => events[2]{id,action}=1,login;2,upload
const roundTrip = Cton.load(cton);
// => same as payload# CLI usage
npx cton input.json
npx cton --to-json data.cton
npx cton --stats input.json- Shorter prompts: CTON removes braces, indentation, and repeated keys.
- Schema hints built-in: arrays include length and tables include headers.
- Deterministic output: round-trip safe and validates structure.
- LLM-friendly: small grammar + clear guardrails for generation.
task=planning,urgent=true,id=123
user(name=Ada,settings(theme=dark))
tags[3]=ruby,gem,llm
files[2]{name,size}=README.md,1024;lib/cton.rb,2048
System prompt template:
You are an expert in CTON (Compact Token-Oriented Notation). Convert between JSON and CTON following the rules below and preserve the schema exactly.
Rules:
1. Do not wrap the root in `{}`.
2. Objects use `key=value` and nested objects use `key(...)`.
3. Arrays are `key[N]=v1,v2` and table arrays are `key[N]{k1,k2}=v1,v2;v1,v2`.
4. Use unquoted literals for `true`, `false`, and `null`.
5. Quote strings containing reserved characters (`,`, `;`, `=`, `(`, `)`) or whitespace.
6. Always keep array length and table headers accurate.Few-shot example:
JSON: {"team":[{"id":1,"name":"Ada"},{"id":2,"name":"Lin"}]}
CTON: team[2]{id,name}=1,Ada;2,Lin
CTON ships with a schema DSL for validation inside your LLM pipeline.
import * as Cton from 'cton-js';
const schema = Cton.schema(b => b.object({}, builder => {
builder.key("user", b.object({}, userBuilder => {
userBuilder.key("id", b.integer());
userBuilder.key("name", b.string());
userBuilder.optionalKey("role", b.enum("admin", "viewer"));
}));
builder.key("tags", b.array({ of: b.string() }));
}));
const result = Cton.validateSchema(payload, schema);
console.log(result.valid); // true/falseHandle newline-delimited CTON streams efficiently:
import * as fs from 'node:fs';
import * as Cton from 'cton-js';
// Reading stream
const readable = fs.createReadStream('events.cton', { encoding: 'utf-8' });
const reader = Cton.StreamReader(readable);
for await (const event of reader) {
// process event
}
// Writing stream
const writable = fs.createWriteStream('events.cton');
Cton.dumpStream(events, writable);CTON-B is an optional binary envelope for compact transport (with optional compression):
import * as Cton from 'cton-js';
const binary = Cton.dumpBinary(payload);
const roundTrip = Cton.loadBinary(binary);CLI:
npx cton --to-binary input.json > output.ctonb
npx cton --from-binary output.ctonbNote: --stream with binary assumes newline-delimited binary frames.
CTON focuses on throughput: memoized table schemas, low-allocation scalar streams, and fast boundary detection for inline docs.
Run benchmarks:
npm test
node bench/benchmark.jsnpx cton [input] # auto-detect JSON/CTON
npx cton --to-json input.cton # CTON → JSON
npx cton --to-cton input.json # JSON → CTON
npx cton --to-binary input.json # JSON → CTON-B
npx cton --from-binary input.ctonb
npx cton --minify input.json # no separators
npx cton --pretty input.json
npx cton --stream input.ndjson
npx cton --schema schema.js input.ctonEncode a JavaScript value to CTON string.
Options:
separator(string): Separator between top-level entries (default:'\n')pretty(boolean): Pretty print with indentation (default:false)decimalMode(string): Float precision mode:'fast'or'precise'(default:'fast')comments(object): Comments to include (key → comment string)
Parse a CTON string to JavaScript value.
Options:
symbolizeNames(boolean): Convert keys to Symbols (default:false)
Validate a CTON string without fully parsing. Returns a ValidationResult.
Check if a CTON string is valid. Returns boolean.
Define a schema using the DSL.
const schema = Cton.schema(b => b.object({}, builder => {
builder.key("name", b.string());
builder.key("age", b.optionalKey(b.integer()));
}));Validate data against a schema definition.
Get token statistics comparing CTON vs JSON. Returns a Stats object.
Get statistics as a plain object.
Stream parse CTON documents from a readable stream. Returns an async generator.
Stream encode CTON documents to a writable stream.
Encode to CTON-B (binary) format. Returns a Buffer.
Options:
compress(boolean): Enable compression (default:true)
Decode from CTON-B (binary) format.
Register a custom type handler.
import * as Cton from 'cton-js';
class Money {
constructor(cents, currency) {
this.cents = cents;
this.currency = currency;
}
}
Cton.registerType(Money, { as: 'object' }, money => ({
amount: money.cents,
currency: money.currency
}));Unregister a custom type handler.
Clear all custom type handlers.
npm install # install dependencies
npm test # run tests
node bin/cton.js # interactive playgroundBug reports and pull requests are welcome at https://github.com/skorotkiewicz/cton-js. Please follow the Code of Conduct.
MIT © Sebastian Korotkiewicz MIT © Davide Santangelo