toon2json

Convert between TOON and JSON formats bidirectionally. This package provides a simple and efficient way to encode JSON objects to TOON format and decode TOON strings back to JSON.

Features

✨ Bidirectional Conversion - Seamlessly convert between TOON and JSON formats 🚀 Fast & Lightweight - Minimal dependencies with zero external runtime dependencies
🔒 Type-Safe - Full TypeScript support with type definitions included 🛠️ CLI Tool - Command-line interface for quick conversions ✅ Well Tested - Comprehensive test coverage

Installation

npm

npm install toon2json

yarn

yarn add toon2json

pnpm

pnpm add toon2json

Usage

As a Module

Encode JSON to TOON

import { encode } from 'toon2json';

const data = {
  name: 'John Doe',
  age: 30,
  email: '[email protected]',
  active: true,
  tags: ['developer', 'nodejs'],
  address: {
    city: 'New York',
    zip: '10001'
  }
};

const toonString = encode(data);
console.log(toonString);
// Output: {name="John Doe";age=30;email="[email protected]";active=true;tags=["developer";"nodejs"];address={city="New York";zip="10001"}}

Decode TOON to JSON

import { decode } from 'toon2json';

const toonString = '{name="John Doe";age=30;active=true}';
const jsonObject = decode(toonString);
console.log(jsonObject);
// Output: { name: 'John Doe', age: 30, active: true }

Round-Trip Conversion

import { encode, decode } from 'toon2json';

const original = { message: 'Hello World', count: 42 };
const encoded = encode(original);
const decoded = decode(encoded);

console.log(decoded); // { message: 'Hello World', count: 42 }

CLI Usage

Convert files from the command line:

# Encode JSON file to TOON
toon2json encode input.json output.toon

# Decode TOON file to JSON
toon2json decode input.toon output.json

# Get help
toon2json --help

TOON Format Specification

TOON is a lightweight text format similar to JSON but with different syntax:

Data Types

| Type | Example | |------|---------| | String | "hello" | | Number | 42, 3.14, -5 | | Boolean | true, false | | Null | null | | Array | ["a"; "b"; "c"] (semicolon-separated) | | Object | {key="value"; number=42} |

Format Rules

• Objects: Enclosed in {}, key-value pairs separated by ;, keys and values separated by =
• Arrays: Enclosed in [], elements separated by ;
• Strings: Enclosed in ""
• Numbers: Unquoted integers and floats
• Booleans & Null: Unquoted literals (true, false, null)
• Escaping: Use \ to escape special characters (\=, \;, \\)

Examples

# Simple object
{name="Alice"; age=28}

# Nested structure
{
  user={
    id=1;
    name="Bob";
    active=true
  };
  roles=["admin"; "user"]
}

# Array of objects
[
  {id=1; name="Item 1"};
  {id=2; name="Item 2"}
]

API Reference

encode(obj: any): string

Converts a JavaScript object to TOON format string.

Parameters:

• obj (any): The JavaScript object to encode (must be JSON-serializable)

Returns: string - TOON formatted string

Example:

const toon = encode({ key: 'value', num: 123 });

decode(input: string): any

Converts a TOON format string to a JavaScript object.

Parameters:

• input (string): The TOON formatted string to decode

Returns: any - Decoded JavaScript object

Example:

const obj = decode('{key="value"; num=123}');

TypeScript Support

This package includes complete TypeScript type definitions:

import { encode, decode, JSONValue, JSONObject } from 'toon2json';

const data: JSONObject = {
  name: 'Example',
  count: 5
};

const encoded: string = encode(data);
const decoded: JSONValue = decode(encoded);

Testing

Run the test suite:

npm test

Run tests in watch mode:

npm run test:watch

Linting & Formatting

Check code quality:

npm run lint

Fix formatting issues:

npm run format

Building

Build TypeScript to JavaScript:

npm run build

Clean build artifacts:

npm run clean

Repository

GitHub

License

ISC

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues, questions, or suggestions, please open an issue on GitHub.