{"id":51406356,"url":"https://github.com/skorotkiewicz/cton-js","last_synced_at":"2026-07-04T11:04:39.724Z","repository":{"id":349484772,"uuid":"1202530968","full_name":"skorotkiewicz/cton-js","owner":"skorotkiewicz","description":"CTON (Compact Token-Oriented Notation) - A token-efficient, JSON-compatible wire format built for LLM prompts","archived":false,"fork":false,"pushed_at":"2026-04-06T06:18:06.000Z","size":44,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-06T08:15:12.375Z","etag":null,"topics":["compact","cton","format","json","llm","notation","serialization","wire-format"],"latest_commit_sha":null,"homepage":"http://sekor.eu.org/cton-js/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/skorotkiewicz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-06T05:49:22.000Z","updated_at":"2026-04-06T06:25:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/skorotkiewicz/cton-js","commit_stats":null,"previous_names":["skorotkiewicz/cton-js"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/skorotkiewicz/cton-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skorotkiewicz%2Fcton-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skorotkiewicz%2Fcton-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skorotkiewicz%2Fcton-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skorotkiewicz%2Fcton-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/skorotkiewicz","download_url":"https://codeload.github.com/skorotkiewicz/cton-js/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skorotkiewicz%2Fcton-js/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35119103,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["compact","cton","format","json","llm","notation","serialization","wire-format"],"created_at":"2026-07-04T11:04:39.071Z","updated_at":"2026-07-04T11:04:39.716Z","avatar_url":"https://github.com/skorotkiewicz.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CTON\n\n[![npm version](https://badge.fury.io/js/cton-js.svg)](https://www.npmjs.com/package/cton-js)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/skorotkiewicz/cton-js/blob/master/LICENSE)\n\nCTON (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.\n\n**CTON is designed to be the reference language for LLM data exchange**: short, deterministic, schema-aware.\n\n---\n\n## Quickstart\n\n```bash\nnpm install cton-js\n```\n\n```javascript\nconst Cton = require('cton-js');\n\nconst payload = {\n  user: { id: 42, name: \"Ada\" },\n  tags: [\"llm\", \"compact\"],\n  events: [\n    { id: 1, action: \"login\" },\n    { id: 2, action: \"upload\" }\n  ]\n};\n\nconst cton = Cton.dump(payload);\n// =\u003e user(id=42,name=Ada)\n// =\u003e tags[2]=llm,compact\n// =\u003e events[2]{id,action}=1,login;2,upload\n\nconst roundTrip = Cton.load(cton);\n// =\u003e same as payload\n```\n\n```bash\n# CLI usage\nnpx cton input.json\nnpx cton --to-json data.cton\nnpx cton --stats input.json\n```\n\n---\n\n## Why CTON for LLMs?\n\n- **Shorter prompts**: CTON removes braces, indentation, and repeated keys.\n- **Schema hints built-in**: arrays include length and tables include headers.\n- **Deterministic output**: round-trip safe and validates structure.\n- **LLM-friendly**: small grammar + clear guardrails for generation.\n\n---\n\n## CTON in 60 seconds\n\n### Objects \u0026 Scalars\n\n```text\ntask=planning,urgent=true,id=123\n```\n\n### Nested Objects\n\n```text\nuser(name=Ada,settings(theme=dark))\n```\n\n### Arrays \u0026 Tables\n\n```text\ntags[3]=ruby,gem,llm\nfiles[2]{name,size}=README.md,1024;lib/cton.rb,2048\n```\n\n---\n\n## LLM Prompt Kit (Recommended)\n\nSystem prompt template:\n\n```markdown\nYou are an expert in CTON (Compact Token-Oriented Notation). Convert between JSON and CTON following the rules below and preserve the schema exactly.\n\nRules:\n1. Do not wrap the root in `{}`.\n2. Objects use `key=value` and nested objects use `key(...)`.\n3. Arrays are `key[N]=v1,v2` and table arrays are `key[N]{k1,k2}=v1,v2;v1,v2`.\n4. Use unquoted literals for `true`, `false`, and `null`.\n5. Quote strings containing reserved characters (`,`, `;`, `=`, `(`, `)`) or whitespace.\n6. Always keep array length and table headers accurate.\n```\n\nFew-shot example:\n\n```text\nJSON: {\"team\":[{\"id\":1,\"name\":\"Ada\"},{\"id\":2,\"name\":\"Lin\"}]}\nCTON: team[2]{id,name}=1,Ada;2,Lin\n```\n\n---\n\n## Schema Validation (1.0.0)\n\nCTON ships with a schema DSL for validation inside your LLM pipeline.\n\n```javascript\nimport * as Cton from 'cton-js';\n\nconst schema = Cton.schema(b =\u003e b.object({}, builder =\u003e {\n  builder.key(\"user\", b.object({}, userBuilder =\u003e {\n    userBuilder.key(\"id\", b.integer());\n    userBuilder.key(\"name\", b.string());\n    userBuilder.optionalKey(\"role\", b.enum(\"admin\", \"viewer\"));\n  }));\n  builder.key(\"tags\", b.array({ of: b.string() }));\n}));\n\nconst result = Cton.validateSchema(payload, schema);\nconsole.log(result.valid); // true/false\n```\n\n---\n\n## Streaming IO (1.0.0)\n\nHandle newline-delimited CTON streams efficiently:\n\n```javascript\nimport * as fs from 'node:fs';\nimport * as Cton from 'cton-js';\n\n// Reading stream\nconst readable = fs.createReadStream('events.cton', { encoding: 'utf-8' });\nconst reader = Cton.StreamReader(readable);\nfor await (const event of reader) {\n  // process event\n}\n\n// Writing stream\nconst writable = fs.createWriteStream('events.cton');\nCton.dumpStream(events, writable);\n```\n\n---\n\n## CTON-B (Binary Mode)\n\nCTON-B is an optional binary envelope for compact transport (with optional compression):\n\n```javascript\nimport * as Cton from 'cton-js';\n\nconst binary = Cton.dumpBinary(payload);\nconst roundTrip = Cton.loadBinary(binary);\n```\n\nCLI:\n\n```bash\nnpx cton --to-binary input.json \u003e output.ctonb\nnpx cton --from-binary output.ctonb\n```\n\nNote: `--stream` with binary assumes newline-delimited binary frames.\n\n---\n\n## Performance \u0026 Benchmarks\n\nCTON focuses on throughput: memoized table schemas, low-allocation scalar streams, and fast boundary detection for inline docs.\n\nRun benchmarks:\n\n```bash\nnpm test\nnode bench/benchmark.js\n```\n\n---\n\n## CLI Reference\n\n```bash\nnpx cton [input]                 # auto-detect JSON/CTON\nnpx cton --to-json input.cton     # CTON → JSON\nnpx cton --to-cton input.json     # JSON → CTON\nnpx cton --to-binary input.json   # JSON → CTON-B\nnpx cton --from-binary input.ctonb\nnpx cton --minify input.json      # no separators\nnpx cton --pretty input.json\nnpx cton --stream input.ndjson\nnpx cton --schema schema.js input.cton\n```\n\n---\n\n## API Reference\n\n### Core Functions\n\n#### `dump(payload, options)` / `generate(payload, options)`\nEncode a JavaScript value to CTON string.\n\n**Options:**\n- `separator` (string): Separator between top-level entries (default: `'\\n'`)\n- `pretty` (boolean): Pretty print with indentation (default: `false`)\n- `decimalMode` (string): Float precision mode: `'fast'` or `'precise'` (default: `'fast'`)\n- `comments` (object): Comments to include (key → comment string)\n\n#### `load(ctonString, options)` / `parse(ctonString, options)`\nParse a CTON string to JavaScript value.\n\n**Options:**\n- `symbolizeNames` (boolean): Convert keys to Symbols (default: `false`)\n\n#### `validate(ctonString)`\nValidate a CTON string without fully parsing. Returns a `ValidationResult`.\n\n#### `isValid(ctonString)`\nCheck if a CTON string is valid. Returns boolean.\n\n### Schema Validation\n\n#### `schema(builderFunction)`\nDefine a schema using the DSL.\n\n```javascript\nconst schema = Cton.schema(b =\u003e b.object({}, builder =\u003e {\n  builder.key(\"name\", b.string());\n  builder.key(\"age\", b.optionalKey(b.integer()));\n}));\n```\n\n#### `validateSchema(data, schema)`\nValidate data against a schema definition.\n\n### Statistics\n\n#### `stats(data)`\nGet token statistics comparing CTON vs JSON. Returns a `Stats` object.\n\n#### `statsHash(data)`\nGet statistics as a plain object.\n\n### Streaming\n\n#### `loadStream(io, options)`\nStream parse CTON documents from a readable stream. Returns an async generator.\n\n#### `dumpStream(enumerable, io, options)`\nStream encode CTON documents to a writable stream.\n\n### Binary\n\n#### `dumpBinary(data, options)`\nEncode to CTON-B (binary) format. Returns a `Buffer`.\n\n**Options:**\n- `compress` (boolean): Enable compression (default: `true`)\n\n#### `loadBinary(binary)`\nDecode from CTON-B (binary) format.\n\n### Type Registry\n\n#### `registerType(constructor, options, transform)`\nRegister a custom type handler.\n\n```javascript\nimport * as Cton from 'cton-js';\n\nclass Money {\n  constructor(cents, currency) {\n    this.cents = cents;\n    this.currency = currency;\n  }\n}\n\nCton.registerType(Money, { as: 'object' }, money =\u003e ({\n  amount: money.cents,\n  currency: money.currency\n}));\n```\n\n#### `unregisterType(constructor)`\nUnregister a custom type handler.\n\n#### `clearTypeRegistry()`\nClear all custom type handlers.\n\n---\n\n## Development\n\n```bash\nnpm install        # install dependencies\nnpm test           # run tests\nnode bin/cton.js   # interactive playground\n```\n\n---\n\n## Contributing\n\nBug reports and pull requests are welcome at https://github.com/skorotkiewicz/cton-js. Please follow the Code of Conduct.\n\n## License\n\nMIT © [Sebastian Korotkiewicz](https://github.com/skorotkiewicz)\nMIT © [Davide Santangelo](https://github.com/davidesantangelo)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskorotkiewicz%2Fcton-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskorotkiewicz%2Fcton-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskorotkiewicz%2Fcton-js/lists"}