toon-formatter 2.0.0 → 2.1.1

package/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.1] - 2025-12-18
+
+### Added
+- **🔄 Unified Format Converters**
+  - New classes: `JsonConverter`, `YamlConverter`, `XmlConverter`, and `CsvConverter`
+  - Direct translation between formats (e.g., XML ↔ JSON, CSV ↔ YAML)
+  - Full encryption middleware support for all unified converters
+  - Static and Instance API parity across all converters
+- **📝 Enhanced Mixed-Text Support**
+  - Standardized mixed-text extraction for JSON, XML, and CSV
+  - Preserves surrounding text while converting embedded data blocks
+- **📦 Improved Packaging**
+  - Specific exports for all converters in `package.json`
+  - Fixed Node.js XML support by moving `xmldom` to production dependencies
+- **📚 Documentation Hub**
+  - Comprehensive README updates with Unified Converter examples
+  - New `toon-formatter.json` documentation for the web platform
+
+### Changed
+- Standardized `returnJson` default to `false` (returns objects/arrays) for consistency
+- Refined internal conversion logic to better handle edge cases in mixed-text scenarios
+- Improved package keywords and description for better SEO
+
 ## [2.0.0] - 2025-12-08
 
 ### Added
@@ -65,6 +88,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Migration Guide
 
+### From v2.0 to v2.1
+
+**To use Unified Converters:**
+
+```javascript
+import { JsonConverter, XmlConverter } from 'toon-formatter';
+
+// Direct format-to-format
+const xml = JsonConverter.toXml({ name: 'Alice' });
+
+// With encryption
+const converter = new JsonConverter(encryptor);
+const encryptedXml = converter.toXml({ name: 'Alice' }, { conversionMode: 'export' });
+```
+
 ### From v1.x to v2.0
 
 **No changes required!** Version 2.0 is fully backward compatible.
@@ -73,7 +111,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ```javascript
 // Old code (still works)
-import { ToonConverter } from 'toon-formatter';
+import ToonConverter from 'toon-formatter';
 const toon = ToonConverter.fromJson(data);
 
 // New code (with encryption)

package/README.md

@@ -1,9 +1,14 @@
 # 🚀 TOON Converter
 
-A lightweight, zero-dependency* library to convert between **TOON** (Token-Oriented Object Notation) and popular data formats (JSON, YAML, XML, CSV).
+A lightweight library to convert between **TOON** (Token-Oriented Object Notation) and popular data formats (JSON, YAML, XML, CSV).
 
 **Reduce your LLM token costs by up to 40%** using the TOON format!
 
+- **Documentation**: https://toonformatter.net/docs.html?package=toon-formatter
+- **Source Code**: https://github.com/ankitpal181/toon-formatter-lib
+- **Bug Reports**: https://github.com/ankitpal181/toon-formatter-lib/issues
+- **POC Tool**: https://toonformatter.net/
+
 \* *Only external dependencies: `js-yaml` and `papaparse` for YAML and CSV parsing*
 
 ---
@@ -1081,6 +1086,152 @@ ToonConverter.toJsonAsync(toonString, returnJson?)
 
 ---
 
+### Unified Format Converters (v2.0.0+)
+
+The library now includes specialized, unified converters for each major format. These are perfect when you need to convert between non-TOON formats (like XML to JSON or CSV to YAML) while still having access to TOON and encryption features.
+
+#### Available Unified Converters:
+- `JsonConverter`: Specialized in JSON input/output
+- `YamlConverter`: Specialized in YAML input/output
+- `XmlConverter`: Specialized in XML input/output
+- `CsvConverter`: Specialized in CSV input/output
+
+#### Example: Cross-Format Conversion
+```javascript
+import { XmlConverter, YamlConverter } from 'toon-formatter';
+
+// Convert XML directly to YAML
+const xmlData = '<user><name>Alice</name></user>';
+const yamlData = XmlConverter.toYaml(xmlData);
+
+// Convert YAML directly to CSV
+const csvData = YamlConverter.toCsv("name: Alice\nrole: admin");
+```
+
+---
+
+### JsonConverter Class
+
+Specialized for JSON-centric workflows. It can convert JSON to any format and any format back to JSON.
+
+#### Instance Methods (with Encryption)
+```javascript
+import { JsonConverter, Encryptor } from 'toon-formatter';
+
+const converter = new JsonConverter(new Encryptor(key, 'aes-256-gcm'));
+
+// JSON -> TOON (Encrypted)
+const encryptedToon = converter.toToon(data, { conversionMode: 'export' });
+
+// XML -> JSON (Decrypted)
+const jsonData = converter.fromXml(encryptedXml, { conversionMode: 'ingestion' });
+```
+
+#### Static Methods (No Encryption)
+```javascript
+// Convert TOON to JSON object
+const obj = JsonConverter.fromToon(toonString);
+
+// Convert TOON to JSON string
+const json = JsonConverter.fromToon(toonString, { returnJson: true });
+
+// Convert JSON to XML
+const xml = JsonConverter.toXml({ name: "Alice" });
+```
+
+**Available Methods:**
+- `fromToon(toonString, options?)` / `fromToonAsync(toonString, options?)`
+- `toToon(data, options?)` / `toToonAsync(data, options?)`
+- `fromYaml(yamlString, options?)` / `fromYamlAsync(yamlString, options?)`
+- `toYaml(data, options?)` / `toYamlAsync(data, options?)`
+- `fromXml(xmlString, options?)` / `fromXmlAsync(xmlString, options?)`
+- `toXml(data, options?)` / `toXmlAsync(data, options?)`
+- `fromCsv(csvString, options?)` / `fromCsvAsync(csvString, options?)`
+- `toCsv(data, options?)` / `toCsvAsync(data, options?)`
+
+---
+
+### YamlConverter Class
+
+Specialized for YAML workflows.
+
+#### Usage Example
+```javascript
+import { YamlConverter } from 'toon-formatter';
+
+// YAML to TOON
+const toon = YamlConverter.fromToon(testToon);
+
+// YAML to JSON
+const json = YamlConverter.toJson(yamlString, { returnJson: true });
+```
+
+**Available Methods:**
+- `fromToon(toonString, options?)` / `fromToonAsync(toonString, options?)`
+- `toToon(yamlString, options?)` / `toToonAsync(yamlString, options?)`
+- `fromJson(jsonData, options?)` / `fromJsonAsync(jsonData, options?)`
+- `toJson(yamlString, options?)` / `toJsonAsync(yamlString, options?)`
+- `fromXml(xmlString, options?)` / `fromXmlAsync(xmlString, options?)`
+- `toXml(yamlString, options?)` / `toXmlAsync(yamlString, options?)`
+- `fromCsv(csvString, options?)` / `fromCsvAsync(csvString, options?)`
+- `toCsv(yamlString, options?)` / `toCsvAsync(yamlString, options?)`
+
+---
+
+### XmlConverter Class
+
+Specialized for XML workflows. Supports mixed-text extraction automatically.
+
+#### Usage Example
+```javascript
+import { XmlConverter } from 'toon-formatter';
+
+// XML to TOON
+const toon = XmlConverter.fromToon(xmlString);
+
+// JSON to XML
+const xml = XmlConverter.fromJson(jsonData);
+```
+
+**Available Methods:**
+- `fromToon(toonString, options?)` / `fromToonAsync(toonString, options?)`
+- `toToon(xmlString, options?)` / `toToonAsync(xmlString, options?)`
+- `fromJson(jsonData, options?)` / `fromJsonAsync(jsonData, options?)`
+- `toJson(xmlString, options?)` / `toJsonAsync(xmlString, options?)`
+- `fromYaml(yamlString, options?)` / `fromYamlAsync(yamlString, options?)`
+- `toYaml(xmlString, options?)` / `toYamlAsync(xmlString, options?)`
+- `fromCsv(csvString, options?)` / `fromCsvAsync(csvString, options?)`
+- `toCsv(xmlString, options?)` / `toCsvAsync(xmlString, options?)`
+
+---
+
+### CsvConverter Class
+
+Specialized for CSV workflows.
+
+#### Usage Example
+```javascript
+import { CsvConverter } from 'toon-formatter';
+
+// CSV to TOON
+const toon = CsvConverter.fromToon(csvString);
+
+// JSON to CSV
+const csv = CsvConverter.fromJson(jsonData);
+```
+
+**Available Methods:**
+- `fromToon(toonString, options?)` / `fromToonAsync(toonString, options?)`
+- `toToon(csvString, options?)` / `toToonAsync(csvString, options?)`
+- `fromJson(jsonData, options?)` / `fromJsonAsync(jsonData, options?)`
+- `toJson(csvString, options?)` / `toJsonAsync(csvString, options?)`
+- `fromYaml(yamlString, options?)` / `fromYamlAsync(yamlString, options?)`
+- `toYaml(csvString, options?)` / `toYamlAsync(csvString, options?)`
+- `fromXml(xmlString, options?)` / `fromXmlAsync(xmlString, options?)`
+- `toXml(csvString, options?)` / `toXmlAsync(csvString, options?)`
+
+---
+
 ## 🎨 TOON Format Guide
 
 ### Primitives

package/package.json

@@ -1,11 +1,11 @@
 {
     "name": "toon-formatter",
-    "version": "2.0.0",
+    "version": "2.1.1",
     "funding": {
         "type": "github",
         "url": "https://github.com/sponsors/ankitpal181"
     },
-    "description": "A lightweight library to convert between TOON (Token-Oriented Object Notation) and popular data formats (JSON, YAML, XML, CSV) with end-to-end encryption support. Reduce LLM token costs by up to 40%.",
+    "description": "A powerful library to convert between TOON, JSON, YAML, XML, and CSV with end-to-end encryption. Includes Unified Converters for direct format-to-format translation and LLM token optimization.",
     "main": "src/index.js",
     "type": "module",
     "scripts": {
@@ -30,7 +30,11 @@
         "security",
         "crypto",
         "secure-data",
-        "end-to-end-encryption"
+        "end-to-end-encryption",
+        "unified-converter",
+        "json-to-xml",
+        "csv-to-yaml",
+        "xml-to-json"
     ],
     "author": "Ankit Pal",
     "license": "MIT",
@@ -47,11 +51,10 @@
     },
     "dependencies": {
         "js-yaml": "^4.1.0",
-        "papaparse": "^5.4.1"
-    },
-    "devDependencies": {
+        "papaparse": "^5.4.1",
         "xmldom": "^0.6.0"
     },
+    "devDependencies": {},
     "exports": {
         ".": "./src/index.js",
         "./json": "./src/json.js",
@@ -60,6 +63,10 @@
         "./csv": "./src/csv.js",
         "./validator": "./src/validator.js",
         "./utils": "./src/utils.js",
-        "./encryptor": "./src/encryptor.js"
+        "./encryptor": "./src/encryptor.js",
+        "./json-converter": "./src/json_formatter/index.js",
+        "./yaml-converter": "./src/yaml_formatter/index.js",
+        "./xml-converter": "./src/xml_formatter/index.js",
+        "./csv-converter": "./src/csv_formatter/index.js"
     }
 }

package/src/csv.js

@@ -4,38 +4,7 @@
 
 import Papa from 'papaparse';
 import { jsonToToonSync, toonToJsonSync } from './json.js';
-import { extractCsvFromString } from './utils.js';
-
-/**
- * Internal core function to convert pure CSV string to TOON (Async)
- * @param {string} csvString 
- * @returns {Promise<string>}
- */
-function parseCsvToToon(csvString) {
-    return new Promise((resolve, reject) => {
-        Papa.parse(csvString, {
-            header: true,
-            dynamicTyping: true,
-            complete: function (results) {
-                try {
-                    const jsonObject = results.data;
-
-                    if (typeof jsonObject !== "object" || jsonObject === null) {
-                        throw new Error("CSV parsing failed — cannot convert.");
-                    }
-
-                    const toonString = jsonToToonSync(jsonObject);
-                    resolve(toonString);
-                } catch (error) {
-                    reject(error);
-                }
-            },
-            error: function (error) {
-                reject(new Error(`CSV parsing error: ${error.message}`));
-            }
-        });
-    });
-}
+import { extractCsvFromString, flattenObject } from './utils.js';
 
 /**
  * Internal core function to convert pure CSV string to TOON (Sync)
@@ -46,6 +15,7 @@ function parseCsvToToonSync(csvString) {
     const results = Papa.parse(csvString, {
         header: true,
         dynamicTyping: true,
+        skipEmptyLines: true,
     });
 
     if (results.errors && results.errors.length > 0) {
@@ -62,20 +32,9 @@ function parseCsvToToonSync(csvString) {
 }
 
 /**
- * Converts CSV (or mixed text with CSV) to TOON format (Async)
- * @param {string} csvString - CSV formatted string or mixed text
- * @returns {Promise<string>} TOON formatted string
- * @throws {Error} If CSV is invalid
- */
-export async function csvToToon(csvString) {
-    return csvToToonSync(csvString);
-}
-
-/**
- * Converts CSV (or mixed text with CSV) to TOON format (synchronous version)
+ * Converts CSV (or mixed text with CSV) to TOON format (Sync)
  * @param {string} csvString - CSV formatted string or mixed text
  * @returns {string} TOON formatted string
- * @throws {Error} If CSV is invalid
  */
 export function csvToToonSync(csvString) {
     if (!csvString || typeof csvString !== 'string') {
@@ -104,10 +63,18 @@ export function csvToToonSync(csvString) {
 }
 
 /**
- * Converts TOON to CSV format (Synchronous)
+ * Converts CSV (or mixed text with CSV) to TOON format (Async)
+ * @param {string} csvString - CSV formatted string or mixed text
+ * @returns {Promise<string>} TOON formatted string
+ */
+export async function csvToToon(csvString) {
+    return csvToToonSync(csvString);
+}
+
+/**
+ * Converts TOON to CSV format (Sync)
  * @param {string} toonString - TOON formatted string
  * @returns {string} CSV formatted string
- * @throws {Error} If TOON is invalid
  */
 export function toonToCsvSync(toonString) {
     if (!toonString || typeof toonString !== 'string') {
@@ -116,12 +83,14 @@ export function toonToCsvSync(toonString) {
 
     const jsonObject = toonToJsonSync(toonString);
 
-    const csvString = Papa.unparse(jsonObject, {
+    // Flatten the object for CSV
+    const dataToUnparse = Array.isArray(jsonObject)
+        ? jsonObject.map(row => flattenObject(row))
+        : [flattenObject(jsonObject)];
+
+    return Papa.unparse(dataToUnparse, {
         header: true,
-        dynamicTyping: true,
     });
-
-    return csvString;
 }
 
 /**