Type-SafeCompactHuman-ReadableMIT

toonkit

A parser & serializer for TOON — Typed Object Oriented Notation. Transform JSON to compact TOON format and back with built-in type awareness.

$ npm install toonkit

📦

What is toonkit?

Why TOON? Why this library?

toonkit provides two core functions:

toonToJson(input: string) — Parses TOON text into JavaScript objects
jsonToToon(obj: any) — Serializes JavaScript objects to TOON format

Why TOON?

JSON is powerful but verbose. TOON solves this by separating the schema definition from the data rows — like a typed table format. Result: smaller payloads, faster parsing, and type safety built in.

📉

40-60% smaller

No repeated key names

🔤

Human-readable

Plain text, easy to edit

🏷️

Type-safe

Schema declares all types

⚡

Fast parsing

Minimal overhead structure

📥

Installation

npm

npm install toonkit

yarn

yarn add toonkit

pnpm

pnpm add toonkit

🔗

Import & Functions

ES Module Import

import { toonToJson, jsonToToon }
  from "toonkit";

Function Signatures

toonToJson(input: string)Parses TOON text and returns a JavaScript object with all types resolved.

jsonToToon(obj: any)Converts a JavaScript object/array into TOON format string.

🔄

toonToJson()

Parse TOON strings into JavaScript objects

This function reads TOON-formatted text and automatically converts it to a properly-typed JavaScript object. Type codes in the schema determine how each value is parsed.

Usage

const toonString = `
device_id[1]{0:s}:
DEVICE_PRO_01

battery[1]{0:n}:
87

is_active[1]{0:b}:
true
`;

const json = toonToJson(toonString);
// json = { device_id: "DEVICE_PRO_01", battery: 87, is_active: true }

Type Codes Reference

CodeMeaningExampleOutput

sstringManoj"Manoj"

nnumber36.736.7

bbooleantruetrue

nlnullnullnull

jJSON object{"a":1}{ a: 1 }

aarray[1,2,3][1,2,3]

tdtext/date03042026120000"03042026120000"

Note: Type code j and a must contain valid JSON. Use td for raw text that shouldn't be parsed.

Complete Example

TOON Input

device_id[1]{0:s}:
DEVICE_PRO_01

battery[1]{0:n}:
87

temperature[1]{0:n}:
36.7

is_active[1]{0:b}:
true

last_error[1]{0:nl}:
null

location[1]{0:j}:
{"lat":12.9716,"lng":77.5946}

tags[1]{0:a}:
["iot","health","tracker"]

created_at[1]{0:td}:
03042026120000

JavaScript Output

{
  device_id: "DEVICE_PRO_01",
  battery: 87,
  temperature: 36.7,
  is_active: true,
  last_error: null,
  location: { lat: 12.9716, lng: 77.5946 },
  tags: ["iot", "health", "tracker"],
  created_at: "03042026120000"
}

🔄

jsonToToon()

Convert JavaScript objects to TOON format

This function inspects your JavaScript object and automatically detects the type of each value (null, string, number, boolean, array, object). It then generates the appropriate TOON-formatted string.

Type Detection Rules

null → nl
string → s
number → n
boolean → b
Array → a
Object → j (JSON)

Example

JavaScript Input

const obj = {
  device_id: "DEVICE_PRO_01",
  battery: 87,
  temperature: 36.7,
  is_active: true,
  last_error: null,
  location: { lat: 12.9716, lng: 77.5946 },
  tags: ["iot", "health", "tracker"]
};

const toon = jsonToToon(obj);

TOON Output

device_id[1]{0:s}:
DEVICE_PRO_01

battery[1]{0:n}:
87

temperature[1]{0:n}:
36.7

is_active[1]{0:b}:
true

last_error[1]{0:nl}:
null

location[1]{0:j}:
{"lat":12.9716,"lng":77.5946}

tags[1]{0:a}:
["iot","health","tracker"]

🧬

Type Codes Reference

Complete guide to all supported data types

TOON uses single or two-letter codes to declare the type of each field. This allows toonToJson to parse values correctly and jsonToToon to detect types automatically.

sStringManojPlain text, no special escaping needed

nNumber87 or 36.7Integers and floats

bBooleantrue or falseLowercase only, case-sensitive

nlNullnullRepresents null/undefined values

jJSON Object{"a":1}Valid JSON object, auto-parsed

aArray[1,"a",true]Valid JSON array, auto-parsed

tdText/Date03042026120000Raw text, no parsing (good for date strings)

🖥

Express.js Integration

Using toonkit in Node.js / Express APIs

toonkit works seamlessly with Express. Use express.text() middleware to accept TOON payloads and respond with TOON strings.

⚠️ Required: Always call app.use(express.text()) before your routes. Without this, req.body will be empty.

🧪

Testing with Postman

Manual API testing with TOON payloads

Since TOON is plain text, testing is straightforward in Postman or any HTTP client. Follow these steps:

Set Method

Select POST or GET as needed

Add Header

Content-Type: text/plain

Raw Body

In Body tab, select raw → Text. Paste your TOON string.

Send

Hit Send. Response will be TOON text.

Example TOON Body

Postman Body (raw text)

device_id[1]{0:s}:
DEVICE_PRO_01

battery[1]{0:n}:
87

is_active[1]{0:b}:
true

⚡

Performance & Size

Why TOON is more efficient than JSON

JSON repeats every key name in every object. TOON declares the schema once, then uses compact row values. For tabular data with many rows, this saves significant bytes and parsing time.

Size Comparison

Same Data — JSON vs TOON

// JSON: ~145 bytes
{"devices":[{"device_id":"DEVICE_PRO_01","battery":87,"is_active":true},{"device_id":"DEVICE_PRO_02","battery":92,"is_active":false}]}

// TOON: ~90 bytes (38% reduction)
devices[2]{device_id:s,battery:n,is_active:b}:
DEVICE_PRO_01,87,true
DEVICE_PRO_02,92,false

JSON

❌ Keys repeated per row
❌ Nested braces & quotes
❌ Heavier for tables
❌ More to parse

TOON

✅ Keys declared once
✅ CSV-style rows
✅ Compact payloads
✅ Faster to parse

Ready to use toonkit?

Install from npm, import the functions, and start converting between JSON and TOON. Perfect for REST APIs, bots, IoT devices, and any system where payload size matters.

⭐ GitHub 📦 NPM