jtl-format

JTLE/JTSD encoder and decoder utilities for JSON Token-Lean Encoding (JTLE) and JSON Token-Lean Schema Definition (JTSD).

JTLE encodes JSON-compatible data into a compact, token-efficient notation for LLM prompts and outputs. JTSD compresses standard JSON Schema structure into compact hints and validation guidance.

Install

pnpm add jtl-format

Quick Start (Simplified API)

import { encode, decode, parseSchema } from 'jtl-format';

// 1. Parse a JTSD 2.0 Schema
const schema = parseSchema(`
def Item {
  sku: str(2..20) @desc("Stock barcode")
  qty: int(1..99) @default(1)
  price: float
  note: str?
}

root {
  items: [Item]
  status: enum(shipped, pending)
}
`);

const data = {
  status: 'shipped',
  items: [
    { sku: 'A101', qty: 2, price: 14.99, note: 'fragile' },
    { sku: 'B205', qty: 1, price: 89, note: null },
  ],
};

// 2. Encode to lean JTLE payload
const jtle = encode(data, { schema });
console.log(jtle);
// status:shipped
// items:[A101|2|14.99|fragile;B205|1|89|~]

// 3. Decode back to standard JSON object
console.log(decode(jtle, schema));

API Overview

1. Primary Top-Level Operations

| Exported Function | Description | Alias / Replaces | | :--- | :--- | :--- | | encode(data, options?) | Encodes JSON data object to compact JTLE string. | jsonToJtle | | decode(jtle, schema?, options?) | Decodes compact JTLE payload into JSON object. | jtleToJson, parseJtle | | parseSchema(jtsd) | Parses JTSD text definition into a runtime schema object. | decodeJtsd, parseJtsd | | fromJSONSchema(schema) | Compresses JSON Schema object into JTSD text. | jsonSchemaToJtsd | | toJSONSchema(jtsd) | Expands JTSD schema back to a standard JSON Schema. | jtsdToJsonSchema |

2. Namespaced API Modules

For structured, modular access, jtl-format exposes clean namespaces:

import { jtle, jtsd } from 'jtl-format';

// JTLE operations
jtle.encode(data);
jtle.decode(jtleText, schema);
jtle.merge([jtle1, jtle2]);
jtle.validate(jtleText, schema);
jtle.format(jtleText);

// JTSD operations
jtsd.parse(jtsdText);
jtsd.encode(schemaObj);
jtsd.fromJSONSchema(jsonSchemaObj);
jtsd.toJSONSchema(jtsdText);

Benchmark Comparison

┌─────────┬────────┬───────┬───────┬─────────────┬────────────────┬─────────────┬───────────────────┬─────────────────┐
│ (index) │ format │ bytes │ chars │ roughTokens │ tiktokenTokens │ byteSavings │ roughTokenSavings │ tiktokenSavings │
├─────────┼────────┼───────┼───────┼─────────────┼────────────────┼─────────────┼───────────────────┼─────────────────┤
│ 0       │ 'JSON' │ 1473  │ 1473  │ 706         │ 475            │ '-'         │ '-'               │ '-'             │
│ 1       │ 'JTLE' │ 669   │ 669   │ 274         │ 292            │ '55%'       │ '61%'             │ '39%'           │
│ 2       │ 'TOON' │ 1576  │ 1576  │ 385         │ 541            │ '-7%'       │ '45%'             │ '-14%'          │
│ 3       │ 'LEAN' │ 1470  │ 1470  │ 342         │ 504            │ '0%'        │ '52%'             │ '-6%'           │
└─────────┴────────┴───────┴───────┴─────────────┴────────────────┴─────────────┴───────────────────┴─────────────────┘

Development & Testing

pnpm test
pnpm build
pnpm benchmark

License

MIT