json-toon-parser 1.1.1 → 1.1.3

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.3  •  **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,46 +57,114 @@ 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 (Summary)
+# json-toon-parser
+
+[![npm version](https://img.shields.io/npm/v/json-toon-parser.svg)](https://www.npmjs.com/package/json-toon-parser)
+[![npm downloads](https://img.shields.io/npm/dm/json-toon-parser.svg)](https://www.npmjs.com/package/json-toon-parser)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+================================================================================
+
+🚀 json-toon-parser — JSON → TOON converter, token optimizer, and developer toolkit
+
+Convert verbose JSON into compact TOON, reduce LLM token usage, and measure savings.
+
+Perfect for teams and engineers integrating large structured payloads into ChatGPT/OpenAI/Claude prompts or storage pipelines.
+
+Official NPM package: https://www.npmjs.com/package/json-toon-parser
+
+Documentation: `docs/API.md`
+
+================================================================================
+
+## Quick Install
+
+Global (CLI + Web UI):
+
+```bash
+npm install -g json-toon-parser
+```
+
+Programmatic (project):
+
+```bash
+npm install json-toon-parser
+```
+
+Verify:
+
+```bash
+json-toon --version
+json-toon serve
+```
+
+================================================================================
+
+## Why TOON? — The Value Proposition
+
+TOON is a compact, human-friendly serialization optimized for token-efficient LLM prompts. It removes syntactic noise (quotes, braces, commas), reduces repeated keys, and uses concise array and nesting notation — which directly translates to lower API costs and faster transmission.
+
+- Reduce per-request token counts by 40–70% (depends on structure)
+- Keep payloads human-readable and reversible via the TOON library
+- Ideal for prompts, telemetry, logs, and mobile/edge transfers
+
+================================================================================
+
+## Features
+
+- CLI: `serve`, `compare`, `convert`, `update`
+- Web UI: interactive editor, samples, copy & download
+- Programmatic API (TypeScript types included)
+- Token analysis using `gpt-3-encoder` for GPT-style counts
+- Save TOON output with timestamped filenames
 
-## API
+================================================================================
 
-### `compare(jsonData, options?)`
-Compare JSON data with TOON format and calculate token efficiency.
+## Usage Examples
 
-**Parameters:**
-- `jsonData`: Any JSON-serializable data
-- `options`: Optional configuration
-  - `outputDir`: Output directory (default: "output")
-  - `saveToFile`: Save TOON file (default: false)
-  - `prettyJson`: Pretty print JSON (default: true)
-  - `fileName`: Custom filename
+CLI
 
-**Returns:** `ComparisonResult` with token counts and savings
+```bash
+# Start web UI
+json-toon serve
 
-### `compareFile(filePath, options?)`
-Compare JSON file with TOON format.
+# Compare & save TOON
+json-toon compare data/input.json --save
 
-### `convertFile(inputPath, outputPath?)`
-Convert JSON file to TOON format and save.
+# Convert file
+json-toon convert data/input.json output.toon
 
-### `jsonToToon(jsonData)`
-Convert JSON data to TOON format string.
+# Update JSON and produce comparison
+json-toon update data/input.json
+```
 
-### `updateJsonFile(filePath, outputPath?)`
-Update JSON file and generate TOON comparison.
+Programmatic
 
-### `formatResult(result)`
-Format comparison result for display.
+```ts
+import { compare, jsonToToon } from 'json-toon-parser';
+
+const data = { users: [{ id: 1, name: 'Alice' }] };
+const toon = jsonToToon(data);
+const result = compare(data, { saveToFile: false });
+console.log(result.toonOutput);
+```
+
+================================================================================
+
+## Example Comparison
+
+Use this example to demonstrate typical savings — include it in docs, blog posts, or README highlights:
 
-## Example Output
 ```
 ============================================================
 COMPARISON RESULTS
@@ -102,18 +177,39 @@ Output File:     output/data_DateTime.toon
 ============================================================
 ```
 
-## Use Cases
+================================================================================
+
+## When TOON Is Most Effective
+
+- Nested JSON with many structural characters
+- Large arrays of similar objects
+- Repetitive keys repeated across objects
+- Prompts that include large contexts for LLMs
+
+================================================================================
+
+## Performance Notes
 
-- 🔍 **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 counting is approximated with `gpt-3-encoder`. Results may vary slightly by tokenizers used by different LLM providers, but the relative savings are consistent.
 
-## Requirements
+================================================================================
 
-- Node.js >= 18.0.0
+## Links & Resources
+
+- NPM: https://www.npmjs.com/package/json-toon-parser
+- TOON format: https://github.com/toon-format/toon
+- API docs: `docs/API.md`
+
+================================================================================
+
+## Contributing
+
+See `CONTRIBUTING.md` to get started. We welcome PRs, issues, and ideas.
+
+================================================================================
 
 ## License
 
 MIT © Bhushan Chaudhari
+
+================================================================================

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.3",
+  "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,28 +29,99 @@
     "dist",
     "public",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md",
+    "docs"
   ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bhushan020/json-toon-parser.git"
+  },
+  "homepage": "https://github.com/bhushan020/json-toon-parser#readme",
   "keywords": [
     "json",
-    "toon",
     "parser",
     "converter",
     "tokenization",
+    "toon",
+    "toon-format",
+    "toon-parser",
+    "toon-tokenizer",
+    "json-to-toon",
+    "json-toon-parser",
+    "JSON-to-TOON",
     "gpt",
+    "llm",
+    "prompt-optimizer",
+    "token-optimization",
+    "token-efficiency",
     "compression",
-    "format",
-    "efficiency",
-    "token-optimization"
+    "data-compression",
+    "text-compression",
+    "minifier",
+    "custom-format",
+    "format-converter",
+    "webui",
+    "cli",
+    "developer-tools",
+    "nodejs",
+    "javascript",
+    "npm-package",
+    "open-source",
+    "json-optimizer",
+    "json-minifier",
+    "json-transform",
+    "json-formatter",
+    "json-analysis",
+    "json-compression",
+    "structured-data",
+    "structured-format",
+    "compact-format",
+    "compact-data",
+    "lightweight-serialization",
+    "serialization",
+    "deserialization",
+    "data-encoding",
+    "data-decoding",
+    "token-counter",
+    "token-metrics",
+    "token-saver",
+    "llm-tools",
+    "chatgpt-tools",
+    "openai-tools",
+    "ai-developer-tools",
+    "prompt-tools",
+    "prompt-engineering",
+    "payload-optimizer",
+    "text-optimizer",
+    "data-optimizer",
+    "json-cli",
+    "json-webui",
+    "llm-friendly",
+    "prompt-friendly",
+    "structured-compression",
+    "encoding-tools",
+    "decoder",
+    "encoder",
+    "tree-shakeable",
+    "typescript",
+    "ts-library",
+    "backend-tools",
+    "automation-tools",
+    "productivity-tools",
+    "developer-productivity",
+    "dev-cli",
+    "api-tools",
+    "file-conversion",
+    "file-transform",
+    "data-utilities"
   ],
   "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",