https://github.com/codebydusk/hypertoon
HyperToon is a high-performance, type-safe converter for TOON (Token-Oriented Object Notation). It is designed for high-throughput applications where speed and bundle size are critical.
https://github.com/codebydusk/hypertoon
Last synced: about 1 month ago
JSON representation
HyperToon is a high-performance, type-safe converter for TOON (Token-Oriented Object Notation). It is designed for high-throughput applications where speed and bundle size are critical.
- Host: GitHub
- URL: https://github.com/codebydusk/hypertoon
- Owner: codebydusk
- License: mit
- Created: 2026-01-20T20:38:59.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-02-15T20:03:00.000Z (5 months ago)
- Last Synced: 2026-05-24T10:32:19.341Z (about 1 month ago)
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/hypertoon
- Size: 73.2 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# HyperToon 🚀
[](https://bun.sh)
[](https://www.typescriptlang.org/)
[](https://opensource.org/licenses/MIT)
**HyperToon** is a high-performance, type-safe converter for **TOON** (Token-Oriented Object Notation). It is designed for high-throughput applications where **speed** and **bundle size** are critical.
## 🏆 Competitive Benchmarks
We compared `hypertoon` against the Official `@toon-format/toon` and the leading competitor `json-toon` (10,000 records).
| Metric | HyperToon | `json-toon` | `@toon-format/toon` |
|--------|-----------|--------------------------|---------------------------|
| **Bundle Size (Minified)** | 4.9 KB | **🚀 4.5 KB** | 64.4 KB |
| **Bundle Size (Gzipped)** | 1.9 KB | **🚀 1.7 KB** | 13.2 KB |
| **Serialize Speed**| **⚡ 121 ops/s** | 87 ops/s | 16 ops/s |
| **Parse Speed** | **⚡ 83 ops/s** | 39 ops/s | 9 ops/s |
| **Payload (Standard)** | 1.03 MB | **0.69 MB** | 1.63 MB |
| **Payload (Flat)** | 274 KB | **254 KB** | 274 KB |
> **Verdict**: HyperToon is **~39% faster at serialization** and **~2.1x faster at parsing** than the nearest competitor, while being **~13x smaller** than the official library. It trades a tiny size margin against `json-toon` for dramatically superior throughput.
## Features
- ⚡ **Hyper Optimized**: `charCodeAt`-based cursor parser avoids memory spikes and string allocations.
- 🦕 **Bun Native**: Built with Bun for speed and modern standards.
- 🔒 **Type-Safe**: `jsonify()` provides full TypeScript support.
- ✨ **Official Syntax**: Fully compliant with TOON `key: value` specification.
- 🛡️ **Robust**: Handles complex nested JSON objects, unicode, and emojis.
- 📦 **Zero Runtime Dependencies**: Lightweight and dependency-free.
- 🔢 **Type Preservation**: Correctly handles numeric strings vs numbers (e.g., `"1.0"` vs `1`).
## Installation
```bash
bun add hypertoon
# or
npm install hypertoon
```
## Usage
### 1. Serialize (`toonify`)
Convert complex JSON data to TOON format.
```ts
import { toonify } from 'hypertoon';
const data = {
project: "Titanium",
active: true,
metadata: {
version: "1.0", // Preserved as string
tags: ["fast", "secure", "scalable"]
},
users: [
{ id: 1, name: "Alice", role: "Admin", verified: true },
{ id: 2, name: "Bob", role: "User", verified: false }
]
};
const toon = toonify(data);
console.log(toon);
/* Output:
project: Titanium
active: true
metadata:
version: "1.0"
tags[3]:
- fast
- secure
- scalable
users[2]{id,name,role,verified}:
1,Alice,Admin,true
2,Bob,User,false
*/
```
### 2. Parse (`jsonify`)
Parse TOON string back to JSON with full type safety.
```ts
import { jsonify } from 'hypertoon';
interface Config {
server: {
host: string;
port: number;
};
endpoints: string[];
}
const toon = `
server:
host: localhost
port: 8080
endpoints[2]:
- /api/v1
- /health
`;
const config = jsonify(toon);
console.log(config.server.port); // 8080
```
## API Reference
### `toonify(data: unknown): string`
- **data**: The input JSON object or value to serialize.
- **Returns**: A TOON-formatted string.
- **Notes**: Automatically detects tabular data structures for compression.
### `jsonify(toon: string): T`
- **toon**: The input TOON string to parse.
- **Returns**: The parsed object cast to type `T`.
- **Notes**: Supports standard TOON syntax, including tabular arrays and lists.
## Why Use Hypertoon?
When dealing with **large datasets** in web applications, traditional JSON can become a bottleneck. Hypertoon solves this with TOON format—a human-readable, bandwidth-efficient alternative.
### Key Benefits
- **🚀 Faster Serialization**: Hypertoon is ~39% faster than competitors and ~7x faster than the official library
- **⚡ 2x Faster Parsing**: Over 2x the throughput of the nearest competitor at parsing TOON data
- **📉 Bandwidth Savings**: Up to 60% smaller payloads for tabular data without gzip overhead
- **⚡ Performance at Scale**: Cursor-based parser prevents garbage collection pauses with millions of records
- **🔒 Type Safety**: Full TypeScript support with `jsonify()` eliminates runtime surprises
- **🔄 Zero Lock-in**: 100% compatible with the TOON specification
### Real-World Example: API with Large Data
Imagine serving 10,000 user records from your API. Here's how Hypertoon reduces bandwidth and improves performance:
#### Backend (Bun/Node.js)
```ts
import { toonify } from 'hypertoon';
// Fetch 10,000 user records from database
app.get('/api/users', async (req, res) => {
const users = await db.query('SELECT id, name, email, role FROM users LIMIT 10000');
// Serialize to TOON (293 KB vs 1,524 KB for JSON)
const toonData = toonify(users);
res.setHeader('Content-Type', 'application/toon');
res.send(toonData);
});
```
#### Frontend (Browser)
```ts
import { jsonify } from 'hypertoon';
interface User {
id: number;
name: string;
email: string;
role: string;
}
// Fetch and parse TOON data
const response = await fetch('/api/users');
const toonData = await response.text();
// Parse TOON to typed object (saves ~700 KB bandwidth)
const users = jsonify(toonData);
console.log(users[0].name); // Type-safe access
```
**Result**: 54% smaller payload (293 KB vs 704 KB for `json-toon`, 1,075 KB for `@toon-format/toon`) with faster parsing and full type safety.
## Contributing
Contributions are welcome!
1. Clone the repository.
2. Install dependencies: `bun install`
3. Run tests: `bun test`
4. Run benchmarks: `bun run benchmark`
## License
MIT