QuarkV

Ultra-compact key-value format optimized for LLMs

Zero dependencies • Extreme performance • Deeply type-safe

Why QuarkV?

QuarkV is designed to minimize token usage when passing structured data to LLMs while maintaining human readability and extreme parsing performance.

Key Features

• 🎯 Token Efficient: 20-52% smaller than JSON for uniform arrays
• ⚡ Blazing Fast: 20-42% of JSON.parse speed, 5-10x faster than YAML/TOML
• 🔒 Type Safe: Deep TypeScript type inference with as const support
• 🛡️ Readonly by Default: Immutable objects with opt-in mutability
• 📦 Zero Dependencies: No runtime dependencies
• 🎨 Human Readable: Clean, compact syntax

Installation

npm install quarkv

Quick Start

import { parse, stringify } from 'quarkv';

// Parse QuarkV format
const data = parse('name:Alice|age:30|active:true');
// { name: 'Alice', age: 30, active: true }

// Stringify to QuarkV
const quarkv = stringify({ name: 'Bob', age: 25 });
// "name:Bob|age:25"

Format Examples

Simple Object

title:Sample Document|author:John Doe|date:'2024-06-15'|active:true

Uniform Array (52% Smaller than JSON!)

users[3]{id,name,role,joined}:1,Alice,admin,'2023-01-15';2,Bob,user,'2024-02-10';3,Carol,user,'2024-06-05'

Nested Objects

user:{name:Alice|email:[email protected]|settings:{theme:dark|notifications:true}}

Arrays

tags[4]:research,ai,ml,nlp

Performance Benchmarks

| Test Case | JSON | QuarkV | YAML | TOML | |-----------|------|--------|------|------| | Flat Object (50 fields) |||| | Parse Speed | 422K ops/s | 88K ops/s (21%) | 39K ops/s (9%) | 35K ops/s (8%) | | Size | 793 bytes | 657 bytes (-17%) | 708 bytes | 792 bytes | | Uniform Array (100 objects) |||| | Parse Speed | 41K ops/s | 10K ops/s (25%) | 4K ops/s (9%) | - | | Size | 8,157 bytes | 3,884 bytes (-52%) | 9,053 bytes | - | | Mixed Data |||| | Parse Speed | 653K ops/s | 139K ops/s (21%) | 89K ops/s (14%) | 70K ops/s (11%) | | Size | 326 bytes | 234 bytes (-28%) | 338 bytes | 350 bytes |

Key Results:

• ✅ 20-25% of JSON.parse speed - faster than YAML/TOML
• ✅ 20-52% space savings vs JSON
• ✅ 5-10x faster than YAML/TOML
• ✅ Best for uniform arrays (massive space savings)

Run benchmarks: npm run bench

API

parse<T>(input: string, options?): T

interface ParseOptions {
  maxDepth?: number;      // Default: 32
  interning?: boolean;    // Default: false
  mutable?: boolean;      // Default: false
}

// Basic
const obj = parse('name:Alice|age:30');

// Type inference
const typed = parse('count:42') as const;
// type: { readonly count: 42 }

// Mutable
const mut = parse('x:1', { mutable: true });
mut.x = 10; // ✅

stringify(value): string

// Auto-detects uniform arrays
stringify({
  users: [
    { id: 1, name: 'Alice' },
    { id: 2, name: 'Bob' }
  ]
});
// "users[2]{id,name}:1,Alice;2,Bob"

Syntax

| Feature | Syntax | Example | |---------|--------|---------| | Object | key:value\|key:value | name:Alice\|age:30 | | Array | key[size]:item,item | tags[3]:a,b,c | | Uniform Array | key[n]{fields}:v1,v2;... | users[2]{id,name}:1,Alice;2,Bob | | Nested | key:{key:value} | meta:{v:1.0} | | String | 'quoted' or unquoted | name:Alice | | Number | int or float | age:30 or pi:3.14 | | Boolean | true\|false | active:true | | Null | null | val:null |

Delimiters: | (pairs) : (key-value) , (items) ; (rows) { } (objects) [ ] (arrays)

Type Inference

const config = parse('port:3000|host:localhost') as const;
// type: { readonly port: 3000; readonly host: "localhost" }

const nested = parse('user:{name:Alice|age:30}') as const;
// type: { readonly user: { readonly name: "Alice"; readonly age: 30 } }

For large projects, see TypeScript Performance Guide.

Use Cases

LLM Prompts (Primary)

const context = stringify({
  user: { id: 123, role: 'admin' },
  settings: { theme: 'dark' }
});
// 28% fewer tokens than JSON!

const prompt = `Context: ${context}\n\nTask: ...`;

Configuration Files

const config = parse(readFileSync('config.quarkv', 'utf-8'));

Compact API Responses

res.send(stringify(users)); // 20-50% smaller

Error Handling

try {
  parse('invalid syntax');
} catch (e) {
  // QuarkVSyntaxError: ... at line 1, column 5
  // >  1 | invalid syntax
  //              ^
}

Documentation

• Full Specification
• TypeScript Performance
• Benchmarks

Contributing

Contributions welcome! Tests required, benchmarks appreciated.

License

MIT

QuarkV - Because every token counts when talking to LLMs 🚀