emon-js

Efficient Modular Object Notation (EMON) is a schema-driven, token-optimal data format specifically designed for high-efficiency communication between Large Language Models (LLMs), microservices, and IoT devices.

This package provides a robust JavaScript/TypeScript implementation to convert between JSON and EMON, perform lazy-loading queries, and benchmark efficiency.

[!NOTE] Currently, this library specifically supports conversions between EMON and JSON. Support for additional formats like XML and YAML is under development and will be added in future versions.

Why EMON?

Traditional formats like JSON are verbose. They repeat key names for every record and use heavy punctuation, which inflates token counts and increases costs when working with AI APIs (like GPT-4 or Claude).

EMON reduces token usage and file size by 40%–70% by:

• Defining the structure (schema) only once.
• Mapping data values by position rather than keys.
• Removing unnecessary quotes for simple strings.

Installation

Install the package via npm:

npm install emon-js

If you want to use the CLI tool globally, install it with the -g flag:

npm install -g .

Key Features

• Token Optimal: Drastically reduces the "noise" in data payloads.
• Lazy Loading: Use EMON.use() to access specific data records without parsing the entire file.
• Isomorphic: Works perfectly in the Browser, Node.js, and Edge environments.
• CLI Support: Powerful command-line interface for file conversions and benchmarking.
• Strict Typing: Supports string, number, bool, nested objects, and arrays.

CLI Usage

The EMON CLI is the easiest way to convert files and check efficiency stats.

Commands

| Command | Description | | ------- | -------------------------------------- | | tojson | Convert EMON data/file to JSON format. | | toemon | Convert JSON data/file to EMON format. |

Options

• -f, --file: Path to the input file.
• -o, --out: Path to the output file.
• -m, --meta: Show efficiency metrics (size reduction, token estimates).
• -h, --help: Show the help menu.

Examples

1. Quick String Conversion

emon tojson "=1,Alice,true"

2. File Conversion with Stats

emon toemon -f data.json -o data.emon -m

3. Preview JSON from an EMON file

emon tojson -f records.emon

Application Usage

The emon-js library provides a simple and unified API to handle EMON data across various environments. You can use it to convert JSON data, wrap large datasets for efficient lazy access, and analyze token savings directly within your application code.

API Reference

Core Methods (import { EMON } from 'emon-js')

| Method | Parameters | Returns | Description | | ------------- | ----------------- | ------------------------- | --------------------------------------------- | | fromJson | data: any | EmonConversionResult | Converts JSON object/string to EMON. | | toJson | emon: string | any | Converts EMON string to JSON object. | | use | emon: string | EmonWrapper | Creates a lazy-loading wrapper for datasets. | | stats | src, emon | MetaData | Calculates size and token efficiency. |

Node.js Extended Methods (import { EMON } from 'emon-js/node')

| Method | Parameters | Returns | Description | | ------------- | ------------------------- | ------------------------- | ----------------------------------------------------- | | fromJsonFile| path, out? | EmonConversionResult | Reads JSON file and converts to EMON (optional save). | | toJsonFile | path, out? | any | Reads EMON file and converts to JSON (optional save). | | statsFile | jsonPath, emonPath | EmonWrapper | Compares two files and returns efficiency stats. |

1. Basic Conversion (JSON ↔ EMON)

import { EMON } from 'emon-js';

const jsonData = [
    { id: 1, name: "Alice", active: true },
    { id: 2, name: "Bob", active: false }
];

// Convert JSON to EMON
const result = EMON.fromJson(jsonData);
console.log(result.emonString);

/* Output:
#(id:number,name:string,active:bool)[]
=1,Alice,true
=2,Bob,false
*/

const backToJson = EMON.toJson(result.emonString);

2. Functional Wrapper (Lazy Access)

If you have a massive EMON file and only need a specific record, use use() to avoid parsing the whole file:

const wrapper = EMON.use(largeEmonString);

// Access record at index 10 without full parsing
const user = wrapper.at(10); 
console.log(user?.get('name')); 

// Iterate through records
wrapper.forEach((record) => {
  console.log(record.toObject());
});

3. Efficiency Benchmarking

Find out exactly how much you are saving:

const stats = EMON.stats(jsonData, emonString);

console.log(`Reduction: ${stats.efficiency}`); // e.g., "55.20%"
console.log(`Input Size: ${stats.input.size}`);
console.log(`Output Size: ${stats.output.size}`);

4. Node.js File Support

import { EMON } from 'emon-js/node';

// Convert and save to file automatically
EMON.fromJsonFile('./input.json', './output.emon');

// Calculate stats between two files
const fileMetrics = EMON.statsFile('./input.json', './output.emon');

Syntax Overview

Root Schema (Nameless)

The first line defines the fields for the data rows.

#(id:number,name:string,verified:bool)[]

Data Records

Each line starting with = is a record matching the schema order.

=101,Parvez,true

Nested Objects and Arrays

Use {} for nested objects and [] for arrays.

#profile(bio:string,age:number)
#(id:number,user:#profile)
=1,{Developer,30}

Join the Community

we need your help to build the ecosystem for efficient data interchange! EMON is an open-source initiative, and we invite developers to help expand the ecosystem.

• Build Tools: Create plugins for VS Code, JetBrains, or other IDEs.
• Expand Core: Help us implement adapters for XML, YAML, and CSV.
• Porting: We are looking for contributors to port emon-js to Python, Go, C and other languages.
• Feedback: Share your use cases and benchmarks to help us optimize the format.

You can follow the contribution guide to submit your contributions.

Check out our emon-js GitHub Issues or EMON GitHub Issues to see where you can contribute!

License

MIT License

© 2025-Present M B Parvez