json-toon-parser 1.1.1 → 1.1.2

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.1.0] - 2025-11-22
+
+### Added
+- 🌐 **Web UI Server** - Beautiful browser-based interface for JSON to TOON conversion
+- ⚡ **`serve` Command** - Start a local web server with `json-toon serve`
+- 📊 **Real-time Conversion** - Instant token analysis and optimization in the browser
+- 💾 **Download Feature** - Download converted TOON files directly from the UI
+- 🎨 **Sample Data** - Pre-loaded examples (Simple, Array, Nested, Complex)
+- 📋 **Copy/Paste** - Easy copy buttons for JSON and TOON output
+- ✨ **JSON Formatter** - Auto-format messy JSON with one click
+- 📱 **Responsive Design** - Works on desktop, tablet, and mobile devices
+
+### Changed
+- Updated CLI with new `serve` command
+- Enhanced README with Web UI documentation
+- Updated package description
+- Added `public/` directory to published files
+- Improved server output with beautiful ASCII art banner
+
+### Technical
+- Added `server.ts` for HTTP server functionality
+- Created standalone `public/index.html` with embedded TOON library
+- Updated TypeScript build configuration
+- Added new npm scripts: `serve` and `dev`
+
+## [1.0.1] - Previous Release
+
+### Features
+- CLI tool for JSON to TOON conversion
+- Compare, convert, and update commands
+- Token efficiency analysis
+- Programmatic API support

package/README.md

@@ -1,18 +1,25 @@
 # json-toon-parser
 
-🚀 Compare and convert JSON to TOON format with token efficiency analysis.
+**Version:** 1.1.2  •  **License:** MIT  •  **Format:** TOON
+
+High-efficiency conversion and analysis toolkit: JSON → TOON with CLI, API, and Web UI server for real‑time token savings. Ideal for reducing LLM prompt payload size and optimizing costs.
 
 ## Installation
+Global (CLI + Web UI):
 ```bash
 npm install -g json-toon-parser
 ```
+Project (Programmatic API):
+```bash
+npm install json-toon-parser
+```
 
-## Quick Start - Web UI
-After installation, start the web server:
+## Quick Start – Web UI
+Start the local server:
 ```bash
 json-toon serve
 ```
-Then open your browser to `http://localhost:3000` and start converting JSON to TOON with a beautiful interface!
+Browse to: `http://localhost:3000` → paste JSON → convert → copy/download TOON.
 
 ## CLI Usage
 ```bash
@@ -50,16 +57,18 @@ const toonString = jsonToToon({ hello: "world" });
 
 ## Features
 
-- 🌐 **Web UI** - Beautiful web interface for easy conversion
-- ✅ Convert JSON to TOON format
-- 📊 Compare token efficiency between formats
-- 💾 Auto-save TOON files with timestamps
-- 🔧 CLI tool for easy usage
-- 📦 Programmatic API for Node.js
-- 🎯 TypeScript support with full type definitions
-- ⚡ Real-time conversion with live stats
+- 🌐 Web UI – Responsive, modern conversion dashboard
+- ✅ Direct JSON → TOON conversion (string or file)
+- 📊 Token efficiency metrics (JSON vs TOON counts, savings %)
+- 💾 Timestamped output file generation
+- 🔧 CLI commands: `serve`, `compare`, `convert`, `update`
+- 📦 Programmatic API with types & tree-shakeable exports
+- ⚡ Real-time stats + sample datasets in UI
+- 🧪 GPT-style token counting via `gpt-3-encoder`
 
-## API
+## API (Summary)
+
+Full reference: see `docs/API.md`.
 
 ### `compare(jsonData, options?)`
 Compare JSON data with TOON format and calculate token efficiency.
@@ -89,7 +98,7 @@ Update JSON file and generate TOON comparison.
 ### `formatResult(result)`
 Format comparison result for display.
 
-## Example Output
+## Example CLI Output
 ```
 ============================================================
 COMPARISON RESULTS
@@ -104,15 +113,21 @@ Output File:     output/data_DateTime.toon
 
 ## Use Cases
 
-- 🔍 **Token Analysis**: Compare token efficiency between formats
-- 💾 **Data Compression**: Convert JSON to more efficient TOON format
-- 📊 **Batch Processing**: Process multiple JSON files
-- 🛠️ **CI/CD Integration**: Automate format conversion
-- 📈 **Cost Optimization**: Reduce API token usage for LLMs
+- 🔍 Token Analysis – Quantify savings before sending payloads
+- 💾 Payload Compression – Minimize size for storage or transfer
+- 📊 Batch Conversion – Automate directory/file transformations
+- 🛠️ CI Integration – Enforce efficiency gates in pipelines
+- 📈 LLM Cost Reduction – Lower prompt token usage dramatically
 
 ## Requirements
 
-- Node.js >= 18.0.0
+- Node.js ≥ 18.0.0
+
+## Contributing & Support
+
+Issues / feature requests: https://github.com/bhushan44/json-toon-parser/issues
+API Reference: `docs/API.md`
+Quick Start Guide: `QUICKSTART.md`
 
 ## License
 

package/dist/cli.js

@@ -7,10 +7,20 @@ import path from "node:path";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const program = new Command();
+// Dynamically derive version from package.json to avoid manual sync issues.
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+let pkgVersion = "0.0.0";
+try {
+    const pkg = require("../package.json");
+    pkgVersion = pkg.version || pkgVersion;
+}
+catch {
+}
 program
     .name("json-toon")
     .description("Compare and convert JSON to TOON format")
-    .version("1.0.1");
+    .version(pkgVersion);
 program
     .command("compare")
     .description("Compare JSON file with TOON format")

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACpF,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;AAE3C,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,4EAA4E;AAC5E,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,IAAI,UAAU,GAAG,OAAO,CAAC;AACzB,IAAI,CAAC;IACH,MAAM,GAAG,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACvC,UAAU,GAAG,GAAG,CAAC,OAAO,IAAI,UAAU,CAAC;AACzC,CAAC;AAAC,MAAM,CAAC;AACT,CAAC;AAED,OAAO;KACJ,IAAI,CAAC,WAAW,CAAC;KACjB,WAAW,CAAC,yCAAyC,CAAC;KACtD,OAAO,CAAC,UAAU,CAAC,CAAC;AAEvB,OAAO;KACJ,OAAO,CAAC,SAAS,CAAC;KAClB,WAAW,CAAC,oCAAoC,CAAC;KACjD,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;KAC1C,MAAM,CAAC,oBAAoB,EAAE,kBAAkB,EAAE,QAAQ,CAAC;KAC1D,MAAM,CAAC,YAAY,EAAE,gBAAgB,EAAE,KAAK,CAAC;KAC7C,MAAM,CAAC,CAAC,IAAY,EAAE,OAA0C,EAAE,EAAE;IACnE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,EAAE;YAC/B,SAAS,EAAE,OAAO,CAAC,MAAM;YACzB,UAAU,EAAE,OAAO,CAAC,IAAI;SACzB,CAAC,CAAC;QACH,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QACxE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,OAAO;KACJ,OAAO,CAAC,SAAS,CAAC;KAClB,WAAW,CAAC,kCAAkC,CAAC;KAC/C,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;KACtC,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;KACxC,MAAM,CAAC,CAAC,KAAa,EAAE,MAAe,EAAE,EAAE;IACzC,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAC9C,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;QACzC,OAAO,CAAC,GAAG,CAAC,cAAc,UAAU,EAAE,CAAC,CAAC;IAC1C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QACxE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,OAAO;KACJ,OAAO,CAAC,QAAQ,CAAC;KACjB,WAAW,CAAC,+CAA+C,CAAC;KAC5D,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;KACzC,MAAM,CAAC,qBAAqB,EAAE,8CAA8C,CAAC;KAC7E,MAAM,CAAC,CAAC,IAAY,EAAE,OAA4B,EAAE,EAAE;IACrD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QACpD,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;QACpC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;QAClC,OAAO,CAAC,GAAG,CAAC,oBAAoB,MAAM,CAAC,eAAe,EAAE,CAAC,CAAC;IAC5D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QACxE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,OAAO;KACJ,OAAO,CAAC,OAAO,CAAC;KAChB,WAAW,CAAC,iDAAiD,CAAC;KAC9D,MAAM,CAAC,mBAAmB,EAAE,aAAa,EAAE,MAAM,CAAC;KAClD,MAAM,CAAC,CAAC,OAAyB,EAAE,EAAE;IACpC,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IACrD,MAAM,GAAG,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;IAEnD,MAAM,aAAa,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,UAAU,CAAC,EAAE;QAChD,GAAG;QACH,KAAK,EAAE,SAAS;KACjB,CAAC,CAAC;IAEH,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;QAClC,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QACxD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEL,OAAO,CAAC,KAAK,EAAE,CAAC"}

package/docs/API.md

@@ -0,0 +1,185 @@
+# json-toon-parser API Documentation
+
+Version: 1.1.2
+
+The `json-toon-parser` package provides utilities to convert JSON data into the TOON format and analyze token efficiency. It exposes a CLI, programmatic API, and a Web UI server.
+
+## Table of Contents
+- Core Concepts
+- Installation
+- CLI Usage
+- Web UI Server
+- Programmatic API
+  - compare
+  - compareFile
+  - jsonToToon
+  - convertFile
+  - updateJsonFile
+  - formatResult
+- Types
+- Error Handling
+- Performance Notes
+- Examples
+
+---
+## Core Concepts
+TOON is a compact serialization format aimed at reducing token counts when sending structured data to LLMs. This library allows:
+- Measuring token savings between pretty JSON and TOON.
+- Converting individual JSON objects or whole files.
+- Serving a browser-based interface for interactive conversion.
+
+## Installation
+```bash
+npm install -g json-toon-parser
+# or locally
+npm install json-toon-parser
+```
+
+## CLI Usage
+```bash
+# Start Web UI on default port 3000
+json-toon serve
+# Custom port
+json-toon serve --port 8080
+
+# Compare a JSON file and save TOON output
+json-toon compare data.json --save
+
+# Convert JSON file directly
+json-toon convert data.json output.toon
+
+# Update JSON file and output comparison stats
+json-toon update data.json
+```
+
+## Web UI Server
+The `serve` command launches a lightweight HTTP server that serves `public/index.html` and provides a POST `/api/convert` endpoint.
+- Interactive editor for JSON input and TOON output.
+- Shows token metrics: JSON tokens, TOON tokens, savings, efficiency percentage.
+- Provides sample datasets, formatting, copy, and download capabilities.
+
+## Programmatic API
+Import functions from the root export:
+```ts
+import { compare, compareFile, jsonToToon, convertFile, updateJsonFile, formatResult } from 'json-to-toon-parser';
+```
+
+### compare(jsonData, options?)
+Compares raw JSON-serializable data to its TOON representation.
+
+Parameters:
+- `jsonData: unknown` – Any serializable data.
+- `options?: CompareOptions`
+  - `outputDir?: string` (default `output`) – Directory for saved TOON file.
+  - `saveToFile?: boolean` (default `false`) – Whether to write TOON to disk.
+  - `prettyJson?: boolean` (default `true`) – Whether to pretty-print JSON when counting tokens.
+  - `fileName?: string` – Custom base file name.
+
+Returns `ComparisonResult`:
+- `jsonTokens: number`
+- `toonTokens: number`
+- `savings: number`
+- `savingsPercentage: number`
+- `toonOutput: string`
+- `toonOutputPath?: string`
+
+Usage:
+```ts
+const res = compare({ user: 'alice', roles: ['admin','editor'] }, { saveToFile: true });
+console.log(res.savingsPercentage);
+```
+
+### compareFile(filePath, options?)
+Loads JSON from a file, performs comparison, and always saves TOON output.
+
+```ts
+const res = compareFile('data/input.json', { outputDir: 'out' });
+```
+Throws if the file does not exist or contains invalid JSON.
+
+### jsonToToon(jsonData)
+Returns only the TOON string.
+```ts
+const toon = jsonToToon({ a: 1, b: 2 });
+```
+
+### convertFile(inputPath, outputPath?)
+Converts a JSON file to TOON and writes the result. Generates a timestamped path when `outputPath` is omitted.
+```ts
+const outPath = convertFile('data/input.json');
+```
+
+### updateJsonFile(filePath, outputPath?)
+Runs comparison on the existing JSON file and then rewrites (or copies) the JSON file (not mutated content—kept formatted). Returns `ComparisonResult & { updatedJsonPath: string }`.
+```ts
+const updated = updateJsonFile('data/input.json');
+```
+
+### formatResult(result)
+Formats a `ComparisonResult` into a readable multiline string for terminal output.
+```ts
+console.log(formatResult(res));
+```
+
+## Types
+```ts
+interface ComparisonResult {
+  jsonTokens: number;
+  toonTokens: number;
+  savings: number;
+  savingsPercentage: number;
+  toonOutput: string;
+  toonOutputPath?: string;
+}
+
+interface CompareOptions {
+  outputDir?: string;
+  saveToFile?: boolean;
+  prettyJson?: boolean;
+  fileName?: string;
+}
+```
+
+## Error Handling
+- File operations throw when paths are invalid.
+- JSON parsing errors surface with native `SyntaxError` messages.
+- Always wrap CLI or programmatic calls in try/catch for robustness.
+
+## Performance Notes
+- Token counting uses `gpt-3-encoder` for approximate GPT token metrics.
+- Pretty-printing JSON increases token count slightly; disable with `{ prettyJson: false }` for raw comparison.
+- TOON encoding efficiency improves with deeply nested or repetitive structures.
+
+## Examples
+```ts
+import { compareFile } from 'json-to-toon-parser';
+const result = compareFile('data/big.json', { outputDir: 'analysis' });
+console.log(`Saved ${result.savings} tokens (${result.savingsPercentage.toFixed(2)}%)`);
+```
+
+```ts
+import { jsonToToon } from 'json-to-toon-parser';
+const payload = { items: Array.from({ length: 50 }, (_, i) => ({ id: i, flag: i % 2 === 0 })) };
+const toon = jsonToToon(payload);
+// Send toon to LLM or store compactly
+```
+
+## Decoding (If Needed)
+If you need to restore JSON later, use the underlying TOON library directly:
+```ts
+import { decode } from '@toon-format/toon';
+const original = decode(toonString);
+```
+
+## Versioning Policy
+- Patch: Internal fixes / metadata.
+- Minor: New features (e.g., Web UI server added in 1.1.x).
+- Major: Breaking API or CLI changes.
+
+## Contributing
+1. Fork & branch (`feat/my-feature`).
+2. Run `npm run build` before submitting PRs.
+3. Add tests/examples where relevant.
+
+## License
+MIT © Bhushan Chaudhari

package/package.json

@@ -1,9 +1,18 @@
 {
   "name": "json-toon-parser",
-  "version": "1.1.1",
-  "description": "Compare and convert JSON to TOON format with token efficiency analysis - Now with Web UI!",
+  "version": "1.1.2",
+  "description": "Compare and convert JSON to TOON format with token efficiency analysis – includes CLI, API, and Web UI server.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "import": "./dist/server.js"
+    }
+  },
   "bin": {
     "json-toon": "./dist/cli.js"
   },
@@ -20,8 +29,18 @@
     "dist",
     "public",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md",
+    "docs"
   ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bhushan44/json-toon-parser.git"
+  },
+  "homepage": "https://github.com/bhushan44/json-toon-parser#readme",
+  "bugs": {
+    "url": "https://github.com/bhushan44/json-toon-parser/issues"
+  },
   "keywords": [
     "json",
     "toon",
@@ -32,16 +51,16 @@
     "compression",
     "format",
     "efficiency",
-    "token-optimization"
+    "token-optimization",
+    "webui",
+    "cli"
   ],
   "author": "Bhushan Chaudhari <bhushanschaudhari4@gmail.com>",
   "license": "MIT",
   "dependencies": {
     "@toon-format/toon": "^1.0.0",
-    "1.0.1": "^1.0.0",
     "commander": "^12.0.0",
-    "gpt-3-encoder": "^1.1.4",
-    "json-toon-parser": "^1.0.1"
+    "gpt-3-encoder": "^1.1.4"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",