https://github.com/plotdb/toon

Last synced: 29 days ago
JSON representation

Host: GitHub
URL: https://github.com/plotdb/toon
Owner: plotdb
License: mit
Created: 2025-10-29T01:58:57.000Z (7 months ago)
Default Branch: master
Last Pushed: 2025-10-29T04:38:13.000Z (7 months ago)
Last Synced: 2025-10-29T05:36:11.372Z (7 months ago)
Language: LiveScript
Size: 142 KB
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

          # @plotdb/toon

A complete implementation of TOON (Token-Oriented Object Notation) encoder and decoder in LiveScript.

## Features

- Complete bidirectional JSON to TOON conversion

- 100% test pass rate

- 100% round-trip conversion fidelity

- Support for all TOON formats (inline, tabular, list)

- Full quoting rules implementation

- Follows official TOON specification

## Installation

    npm install --save @plotdb/toon

## Usage

### Basic usage

    const { encode, decode } = require('@plotdb/toon');

    // Encode JSON to TOON

    const data = {

      id: 123,

      name: "Ada",

      tags: ["admin", "dev"],

      items: [

        { sku: "A1", qty: 2, price: 9.99 },

        { sku: "B2", qty: 1, price: 14.5 }

      ]

    };

    const toon = encode(data);

    console.log(toon);

    /*

    id: 123

    name: Ada

    tags[2]: admin,dev

    items[2]{sku,qty,price}:

      A1,2,9.99

      B2,1,14.5

    */

    // Decode TOON to JSON

    const decoded = decode(toon);

    console.log(JSON.stringify(decoded) === JSON.stringify(data)); // true

## API

### encode(value, options)

Encode a JSON value to TOON format.

Parameters:

- `value` - Any JSON-serializable value

- `options` (optional)

  - `indent`: Number of spaces per indentation level (default: 2)

  - `delimiter`: Delimiter character `','` | `'\t'` | `'|'` (default: `','`)

  - `lengthMarker`: Whether to use `#` prefix (default: `false`)

Returns: TOON format string

Example:

    const toon = encode({ name: "Ada", age: 30 });

### decode(toonStr, options)

Parse a TOON format string to JSON value.

Parameters:

- `toonStr` - TOON format string

- `options` (optional)

  - `strict`: Strict mode (reserved)

Returns: Parsed JSON value

Example:

    const data = decode("name: Ada\nage: 30");

### Using encoder/decoder classes

    const { encoder, decoder } = require('@plotdb/toon');

    // Use encoder instance with custom options

    const enc = new encoder({ delimiter: '\t' });

    const toon = enc.encode(data);

    // Use decoder instance

    const dec = new decoder();

    const json = dec.decode(toon);

## TOON format examples

### Object

    id: 123

    name: Ada

    active: true

### Nested object

    user:

      id: 123

      name: Ada

### Inline array

    tags[3]: admin,ops,dev

### Tabular array

    items[3]{sku,qty,price}:

      A1,2,9.99

      B2,1,14.5

      C3,5,7.25

### List array

    items[5]:

      - 1

      - text

      - a: 1

      - true

      - null

### Quoted strings

    with_comma: "hello, world"

    with_colon: "key: value"

    looks_like_bool: "true"

## Benefits

### Token savings

According to TOON specification, compared to JSON:

- General data: 30-60% token reduction

- Tabular data: up to 60%+ token reduction

### Use cases

Suitable for:

- Passing data to LLMs

- Large amounts of uniformly structured data

- Token-cost-sensitive applications

Not suitable for:

- API responses (use JSON)

- Database storage (use JSON)

- Direct browser parsing (use JSON)

## Development

### Build

    ./build

### Testing

    # Run all tests

    npm test

    # Run individual tests

    npm run test:encoder    # Encoder tests

    npm run test:decoder    # Decoder and round-trip tests

    npm run test:samples    # Sample files tests

    # Run example

    npm run example

Test results: All tests passed (100% success rate)

### Project structure

    .

    ├── src/

    │   └── index.ls              # Main implementation (~700 lines)

    ├── dist/

    │   ├── index.js              # Compiled JavaScript

    │   └── index.min.js          # Minified version

    ├── tests/                    # Test files

    │   ├── test-encoder.js

    │   ├── test-decoder.js

    │   ├── test-samples.js

    │   └── example.js

    ├── samples/                  # Test samples

    │   ├── simple/

    │   ├── complex/

    │   └── edge-cases/

    └── llm/                      # Development documentation

        ├── spec.md

        ├── DEV.md

        ├── ARCHITECTURE.md

        └── ...

### Documentation

Development documentation:

- [llm/spec.md](llm/spec.md) - TOON format specification

- [llm/DEV.md](llm/DEV.md) - Development guide

- [llm/ARCHITECTURE.md](llm/ARCHITECTURE.md) - Architecture document

- [llm/FINAL_REPORT.md](llm/FINAL_REPORT.md) - Complete implementation report

### Technical specifications

- Language: LiveScript

- Target: Node.js

- Compiler: LiveScript compiler

- Lines of code: ~700 lines

- Test coverage: 100%

## Related links

- [Official TOON specification](https://github.com/johannschopplich/toon)

- [LiveScript official website](https://livescript.net/)

## License

MIT License

## Author

Developed with Claude Code by zbryikt

---

Status: Complete and ready to use

Version: 0.0.1

Last updated: 2025-10-29

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/plotdb/toon

Awesome Lists containing this project

README