🧬 COIL — Compact Object Input Language

Token-optimized structured data encoding for LLM pipelines.

COIL transforms JSON data into a compact, schema-aware format that significantly reduces token usage while remaining fully lossless and reversible. It is designed for use in LLM context windows where every token counts.

Why COIL?

Standard JSON is verbose. When you send large arrays of records, logs, or telemetry data to an LLM, most of the tokens go toward repeating keys and common values — not actual information.

COIL detects table-shaped arrays, builds a value map for repeated entries, and encodes rows positionally. The result is a structure that carries the same meaning in far fewer tokens.

Installation

npm install coil-js

Quick Start

const coil = require("coil-js");
const fs = require("fs");

// Load your data
const data = JSON.parse(fs.readFileSync("data.json", "utf8"));

// Encode to COIL
const encoded = coil.encode(data);

// Decode back to original structure
const decoded = coil.decode(encoded);

// Get compression stats
const stats = coil.stats(data, encoded, decoded);
console.log(stats);

Note: encode() writes a coil_types.json file in your working directory to store column type metadata. decode() reads this same file to restore types correctly. Both calls must happen in the same directory.

CLI

After installing, use the coil command:

# Encode a JSON file
coil encode input.json output.json

# Decode a COIL-encoded file
coil decode encoded.json decoded.json

If no output file is specified, the result is written to out.json.

API Reference

coil.encode(data)

Encodes a JavaScript object or array into COIL format.

COIL automatically:

• Detects arrays of objects (tables) and encodes them positionally
• Builds a greedy value map (vmap) for repeated string values
• Stores column types to coil_types.json in the working directory
• Falls back to returning the original data if encoding would not reduce token count

const encoded = coil.encode(data);
// encoded is a plain JS object — safe to JSON.stringify and store

Returns: A COIL-encoded object with meta and body fields for table blocks, or the original structure where encoding provides no benefit.

coil.decode(encoded)

Restores original data from a COIL-encoded object.

Reads coil_types.json from the working directory to restore column types (numbers, booleans, nulls).

const decoded = coil.decode(encoded);

Returns: The original JavaScript structure.

coil.stats(original, encoded, decoded?)

Returns compression metrics comparing the original and encoded data.

const stats = coil.stats(original, encoded, decoded);
console.log(stats);

Example output:

{
  "original": { "chars": 18300, "bytes": 18300, "tokens": 4575, "words": 2900 },
  "encoded":  { "chars": 6200,  "bytes": 6200,  "tokens": 1550, "words": 1200 },
  "comparison": {
    "token_saving_percent": "66.10",
    "byte_saving_percent": "66.12",
    "twr_original": "1.577",
    "twr_encoded": "1.291"
  },
  "lossless": true
}

twr is the token-to-word ratio — a lower value means more information per token.

If you pass a decoded value as the third argument, stats will also run a lossless check and include the lossless boolean.

coil.isLossless(original, decoded)

Checks whether a decoded result semantically matches the original.

const ok = coil.isLossless(original, decoded);
// true or false

This does a row-by-row canonical comparison, so it is order-independent.

coil.verify(original, encoded)

Decodes the encoded data and runs isLossless in one step.

const { decoded, lossless } = coil.verify(original, encoded);

coil.saveStats(stats, filename?)

Saves a stats object to a JSON file. Default filename is coil_stats.json.

coil.saveStats(stats, "my_stats.json");

coil.info()

Returns metadata about the installed library.

coil.info();
// {
//   library: "coil-js",
//   version: "0.4.0",
//   ecosystem: "node",
//   purpose: "Token-optimized structured data encoding for LLMs"
// }

Full Example

const coil = require("coil-js");
const fs = require("fs");

const data = JSON.parse(fs.readFileSync("data.json", "utf8"));

// Encode
const encoded = coil.encode(data);
fs.writeFileSync("encoded.json", JSON.stringify(encoded, null, 2));

// Decode
const decoded = coil.decode(encoded);
fs.writeFileSync("decoded.json", JSON.stringify(decoded, null, 2));

// Verify and measure
const stats = coil.stats(data, encoded, decoded);
coil.saveStats(stats, "coil_stats.json");

console.log(`Token reduction: ${stats.comparison.token_saving_percent}%`);
console.log(`Lossless: ${stats.lossless}`);

How COIL Works

COIL identifies two patterns in JSON:

Table arrays — arrays where every element is an object (records). COIL extracts the keys into an ordered column list, maps repeated values to short tokens (V1, V2…), and serialises rows as delimited strings. The metadata block stores the column order, value map, and type registry.

Categorical string arrays — arrays of repeated string values. COIL wraps them as single-column tables and applies the same value-map compression.

For everything else (plain objects, mixed arrays, primitives), COIL recurses into the structure and encodes whatever sub-structures it can, leaving the rest unchanged.

Known Limitations

• decode() depends on coil_types.json being present in the working directory. If you encode in one location and decode in another, copy the types file along with the encoded JSON.
• Token counts in stats are estimated using a character-length heuristic (ceil(chars / 4)), not an actual tokenizer. Results are approximate.
• COIL falls back to the original data when encoding would not reduce size, so not every JSON document will be compressed.

License

MIT

Author

Muthukumaran S & Bala Jothi Adithiya S — Creator of the COIL Protocol

Contact - [email protected] , [email protected]

If you use COIL in research, please cite it as:
COIL — Compact Object Input Language, 2026.