toon-formatter 1.1.1 → 2.0.0

package/src/encryptor.js

@@ -0,0 +1,244 @@
+/**
+ * Encryptor Class
+ * 
+ * Handles encryption and decryption of data using specified algorithms.
+ * 
+ * Supported Algorithms:
+ * - 'aes-256-gcm': Symmetric encryption (Node.js crypto). High security, authenticated encryption.
+ * - 'xor': Simple XOR cipher. Low security, good for obfuscation only.
+ * - 'base64': Base64 encoding. No security, just encoding.
+ */
+
+import crypto from 'crypto';
+
+export class Encryptor {
+    /**
+     * Creates an Encryptor instance
+     * @param {string|Buffer|null} key - Encryption key (required for AES-256-GCM and XOR)
+     * @param {string} algorithm - Algorithm to use: 'aes-256-gcm', 'xor', or 'base64'
+     * @throws {Error} If key is missing for algorithms that require it
+     * @throws {Error} If key is invalid for the selected algorithm
+     */
+    constructor(key = null, algorithm = 'aes-256-gcm') {
+        this.key = key;
+        this.algorithm = algorithm.toLowerCase();
+
+        // Validate algorithm
+        const validAlgorithms = ['aes-256-gcm', 'xor', 'base64'];
+        if (!validAlgorithms.includes(this.algorithm)) {
+            throw new Error(`Unsupported algorithm: ${this.algorithm}. Valid options: ${validAlgorithms.join(', ')}`);
+        }
+
+        // Validate key for AES-256-GCM
+        if (this.algorithm === 'aes-256-gcm') {
+            if (!this.key) {
+                throw new Error('Key is required for AES-256-GCM encryption.');
+            }
+            this._validateAesKey();
+        }
+    }
+
+    /**
+     * Generates a random 32-byte (256-bit) key suitable for AES-256-GCM
+     * @returns {Buffer} 32-byte random key
+     * @example
+     * const key = Encryptor.generateKey();
+     * console.log(key.length); // 32
+     */
+    static generateKey() {
+        return crypto.randomBytes(32);
+    }
+
+    /**
+     * Encrypts the provided string data
+     * @param {string} data - Data to encrypt (must be a string)
+     * @returns {string} Encrypted data
+     * @throws {Error} If data is not a string
+     * @throws {Error} If encryption fails
+     */
+    encrypt(data) {
+        if (typeof data !== 'string') {
+            throw new Error('Data to encrypt must be a string.');
+        }
+
+        switch (this.algorithm) {
+            case 'aes-256-gcm':
+                return this._aesEncrypt(data);
+            case 'xor':
+                return this._xorEncrypt(data);
+            case 'base64':
+                return Buffer.from(data, 'utf-8').toString('base64');
+            default:
+                throw new Error(`Unsupported algorithm: ${this.algorithm}`);
+        }
+    }
+
+    /**
+     * Decrypts the provided encrypted string data
+     * @param {string} encryptedData - Data to decrypt (must be a string)
+     * @returns {string} Decrypted data
+     * @throws {Error} If encryptedData is not a string
+     * @throws {Error} If decryption fails
+     */
+    decrypt(encryptedData) {
+        if (typeof encryptedData !== 'string') {
+            throw new Error('Data to decrypt must be a string.');
+        }
+
+        switch (this.algorithm) {
+            case 'aes-256-gcm':
+                return this._aesDecrypt(encryptedData);
+            case 'xor':
+                return this._xorDecrypt(encryptedData);
+            case 'base64':
+                try {
+                    return Buffer.from(encryptedData, 'base64').toString('utf-8');
+                } catch (error) {
+                    throw new Error(`Invalid Base64 data: ${error.message}`);
+                }
+            default:
+                throw new Error(`Unsupported algorithm: ${this.algorithm}`);
+        }
+    }
+
+    /**
+     * Validates the AES key length (must be 32 bytes for AES-256)
+     * @private
+     * @throws {Error} If key is not 32 bytes
+     */
+    _validateAesKey() {
+        const keyBuffer = Buffer.isBuffer(this.key) ? this.key : Buffer.from(this.key);
+        if (keyBuffer.length !== 32) {
+            throw new Error(`AES-256-GCM requires a 32-byte (256-bit) key. Provided key is ${keyBuffer.length} bytes.`);
+        }
+    }
+
+    /**
+     * Encrypts text using AES-256-GCM
+     * @private
+     * @param {string} text - Text to encrypt
+     * @returns {string} Encrypted text in format: iv:authTag:encryptedData (all hex)
+     * @throws {Error} If encryption fails
+     */
+    _aesEncrypt(text) {
+        try {
+            // Generate random 12-byte IV (96 bits, recommended for GCM)
+            const iv = crypto.randomBytes(12);
+
+            // Ensure key is a Buffer
+            const keyBuffer = Buffer.isBuffer(this.key) ? this.key : Buffer.from(this.key);
+
+            // Create cipher
+            const cipher = crypto.createCipheriv('aes-256-gcm', keyBuffer, iv);
+
+            // Encrypt
+            let encrypted = cipher.update(text, 'utf-8', 'hex');
+            encrypted += cipher.final('hex');
+
+            // Get authentication tag (16 bytes for GCM)
+            const authTag = cipher.getAuthTag();
+
+            // Return format: iv:authTag:encryptedData (all in hex)
+            return `${iv.toString('hex')}:${authTag.toString('hex')}:${encrypted}`;
+        } catch (error) {
+            throw new Error(`AES-256-GCM encryption failed: ${error.message}`);
+        }
+    }
+
+    /**
+     * Decrypts text using AES-256-GCM
+     * @private
+     * @param {string} encryptedText - Encrypted text in format: iv:authTag:encryptedData
+     * @returns {string} Decrypted text
+     * @throws {Error} If decryption fails or authentication fails
+     */
+    _aesDecrypt(encryptedText) {
+        try {
+            // Split the encrypted text
+            const parts = encryptedText.split(':');
+            if (parts.length !== 3) {
+                throw new Error('Invalid encrypted data format. Expected format: iv:authTag:encryptedData');
+            }
+
+            const iv = Buffer.from(parts[0], 'hex');
+            const authTag = Buffer.from(parts[1], 'hex');
+            const encrypted = parts[2];
+
+            // Ensure key is a Buffer
+            const keyBuffer = Buffer.isBuffer(this.key) ? this.key : Buffer.from(this.key);
+
+            // Create decipher
+            const decipher = crypto.createDecipheriv('aes-256-gcm', keyBuffer, iv);
+            decipher.setAuthTag(authTag);
+
+            // Decrypt
+            let decrypted = decipher.update(encrypted, 'hex', 'utf-8');
+            decrypted += decipher.final('utf-8');
+
+            return decrypted;
+        } catch (error) {
+            throw new Error(`AES-256-GCM decryption failed: ${error.message}`);
+        }
+    }
+
+    /**
+     * Encrypts text using XOR cipher
+     * @private
+     * @param {string} text - Text to encrypt
+     * @returns {string} Encrypted text as hex string
+     * @throws {Error} If key is missing or encryption fails
+     */
+    _xorEncrypt(text) {
+        if (!this.key) {
+            throw new Error('Key is required for XOR cipher.');
+        }
+
+        try {
+            // Convert key and text to buffers
+            const keyBuffer = Buffer.isBuffer(this.key) ? this.key : Buffer.from(String(this.key), 'utf-8');
+            const textBuffer = Buffer.from(text, 'utf-8');
+            const result = Buffer.alloc(textBuffer.length);
+
+            // XOR each byte with corresponding key byte (cycling through key)
+            for (let i = 0; i < textBuffer.length; i++) {
+                result[i] = textBuffer[i] ^ keyBuffer[i % keyBuffer.length];
+            }
+
+            // Return as hex string for safe transport/storage
+            return result.toString('hex');
+        } catch (error) {
+            throw new Error(`XOR encryption failed: ${error.message}`);
+        }
+    }
+
+    /**
+     * Decrypts text using XOR cipher
+     * @private
+     * @param {string} hexText - Encrypted text as hex string
+     * @returns {string} Decrypted text
+     * @throws {Error} If key is missing, format is invalid, or decryption fails
+     */
+    _xorDecrypt(hexText) {
+        if (!this.key) {
+            throw new Error('Key is required for XOR cipher.');
+        }
+
+        try {
+            // Convert key and encrypted data to buffers
+            const keyBuffer = Buffer.isBuffer(this.key) ? this.key : Buffer.from(String(this.key), 'utf-8');
+            const encryptedBuffer = Buffer.from(hexText, 'hex');
+            const result = Buffer.alloc(encryptedBuffer.length);
+
+            // XOR each byte with corresponding key byte (cycling through key)
+            for (let i = 0; i < encryptedBuffer.length; i++) {
+                result[i] = encryptedBuffer[i] ^ keyBuffer[i % keyBuffer.length];
+            }
+
+            return result.toString('utf-8');
+        } catch (error) {
+            throw new Error(`XOR decryption failed: ${error.message}`);
+        }
+    }
+}
+
+export default Encryptor;

package/src/index.js

@@ -23,6 +23,7 @@ import {
     extractXmlFromString,
     extractCsvFromString
 } from './utils.js';
+import { Encryptor } from './encryptor.js';
 
 // Exports
 export {
@@ -32,13 +33,350 @@ export {
     csvToToonSync, csvToToon, toonToCsvSync, toonToCsv,
     validateToonString, validateToonStringSync,
     encodeXmlReservedChars, splitByDelimiter, parseValue, formatValue,
-    extractJsonFromString, extractXmlFromString, extractCsvFromString
+    extractJsonFromString, extractXmlFromString, extractCsvFromString,
+    Encryptor
 };
 
 /**
- * Main converter class for easy usage
+ * Main converter class for TOON format conversions
+ * 
+ * Supports both static usage (backward compatible) and instance usage (with encryption).
+ * 
+ * @example
+ * // Static usage (no encryption) - backward compatible
+ * const toon = ToonConverter.fromJson({ name: "Alice" });
+ * 
+ * @example
+ * // Instance usage with encryption
+ * const key = Encryptor.generateKey();
+ * const encryptor = new Encryptor(key, 'aes-256-gcm');
+ * const converter = new ToonConverter(encryptor);
+ * const encrypted = converter.fromJson({ name: "Alice" }, { conversionMode: 'export' });
  */
 export class ToonConverter {
+    /**
+     * Creates a ToonConverter instance
+     * @param {Encryptor|null} [encryptor=null] - Optional Encryptor instance for encryption support
+     * @example
+     * // Without encryption
+     * const converter = new ToonConverter();
+     * 
+     * @example
+     * // With encryption
+     * const key = Encryptor.generateKey();
+     * const encryptor = new Encryptor(key, 'aes-256-gcm');
+     * const converter = new ToonConverter(encryptor);
+     */
+    constructor(encryptor = null) {
+        this.encryptor = encryptor;
+    }
+
+    // ========================================
+    // Private Helper Methods
+    // ========================================
+
+    /**
+     * Applies encryption logic based on conversion mode (synchronous)
+     * @private
+     * @param {Function} converterFn - The converter function to call
+     * @param {*} data - Data to convert
+     * @param {string} mode - Conversion mode: 'no_encryption', 'middleware', 'ingestion', 'export'
+     * @returns {*} Converted (and possibly encrypted) data
+     */
+    _convertWithEncryption(converterFn, data, mode) {
+        // If no encryptor or mode is 'no_encryption', just convert normally
+        if (!this.encryptor || mode === 'no_encryption') {
+            return converterFn(data);
+        }
+
+        switch (mode) {
+            case 'middleware':
+                // Encrypted → Encrypted (Decrypt → Convert → Re-encrypt)
+                const decrypted = this.encryptor.decrypt(data);
+                const converted = converterFn(decrypted);
+                return this.encryptor.encrypt(converted);
+
+            case 'ingestion':
+                // Encrypted → Plain (Decrypt → Convert)
+                const decryptedData = this.encryptor.decrypt(data);
+                return converterFn(decryptedData);
+
+            case 'export':
+                // Plain → Encrypted (Convert → Encrypt)
+                const plainConverted = converterFn(data);
+                return this.encryptor.encrypt(plainConverted);
+
+            default:
+                return converterFn(data);
+        }
+    }
+
+    /**
+     * Applies encryption logic based on conversion mode (asynchronous)
+     * @private
+     * @param {Function} converterFn - The async converter function to call
+     * @param {*} data - Data to convert
+     * @param {string} mode - Conversion mode: 'no_encryption', 'middleware', 'ingestion', 'export'
+     * @returns {Promise<*>} Converted (and possibly encrypted) data
+     */
+    async _convertWithEncryptionAsync(converterFn, data, mode) {
+        // If no encryptor or mode is 'no_encryption', just convert normally
+        if (!this.encryptor || mode === 'no_encryption') {
+            return await converterFn(data);
+        }
+
+        switch (mode) {
+            case 'middleware':
+                // Encrypted → Encrypted (Decrypt → Convert → Re-encrypt)
+                const decrypted = this.encryptor.decrypt(data);
+                const converted = await converterFn(decrypted);
+                return this.encryptor.encrypt(converted);
+
+            case 'ingestion':
+                // Encrypted → Plain (Decrypt → Convert)
+                const decryptedData = this.encryptor.decrypt(data);
+                return await converterFn(decryptedData);
+
+            case 'export':
+                // Plain → Encrypted (Convert → Encrypt)
+                const plainConverted = await converterFn(data);
+                return this.encryptor.encrypt(plainConverted);
+
+            default:
+                return await converterFn(data);
+        }
+    }
+
+    // ========================================
+    // Instance Methods (Support Encryption)
+    // ========================================
+
+    /**
+     * Convert JSON to TOON (Sync, Instance Method)
+     * @param {*} jsonData - JSON data (object, array, or primitive)
+     * @param {Object} [options={}] - Conversion options
+     * @param {string} [options.conversionMode='no_encryption'] - Encryption mode: 'no_encryption', 'middleware', 'ingestion', 'export'
+     * @returns {string} TOON formatted string (possibly encrypted)
+     */
+    fromJson(jsonData, options = {}) {
+        const { conversionMode = 'no_encryption' } = options;
+        return this._convertWithEncryption(jsonToToonSync, jsonData, conversionMode);
+    }
+
+    /**
+     * Convert JSON to TOON (Async, Instance Method)
+     * @param {*} jsonData - JSON data
+     * @param {Object} [options={}] - Conversion options
+     * @param {string} [options.conversionMode='no_encryption'] - Encryption mode
+     * @returns {Promise<string>} TOON formatted string (possibly encrypted)
+     */
+    async fromJsonAsync(jsonData, options = {}) {
+        const { conversionMode = 'no_encryption' } = options;
+        return this._convertWithEncryptionAsync(jsonToToon, jsonData, conversionMode);
+    }
+
+    /**
+     * Convert TOON to JSON (Sync, Instance Method)
+     * @param {string} toonString - TOON formatted string (possibly encrypted)
+     * @param {Object} [options={}] - Conversion options
+     * @param {string} [options.conversionMode='no_encryption'] - Encryption mode
+     * @param {boolean} [options.returnJson=false] - If true, returns JSON string; if false, returns object
+     * @returns {*} Parsed JSON data (object or string)
+     */
+    toJson(toonString, options = {}) {
+        const { conversionMode = 'no_encryption', returnJson = false } = options;
+        return this._convertWithEncryption(
+            (data) => toonToJsonSync(data, returnJson),
+            toonString,
+            conversionMode
+        );
+    }
+
+    /**
+     * Convert TOON to JSON (Async, Instance Method)
+     * @param {string} toonString - TOON formatted string (possibly encrypted)
+     * @param {Object} [options={}] - Conversion options
+     * @param {string} [options.conversionMode='no_encryption'] - Encryption mode
+     * @param {boolean} [options.returnJson=false] - If true, returns JSON string; if false, returns object
+     * @returns {Promise<*>} Parsed JSON data (object or string)
+     */
+    async toJsonAsync(toonString, options = {}) {
+        const { conversionMode = 'no_encryption', returnJson = false } = options;
+        return this._convertWithEncryptionAsync(
+            (data) => toonToJson(data, returnJson),
+            toonString,
+            conversionMode
+        );
+    }
+
+    /**
+     * Convert YAML to TOON (Sync, Instance Method)
+     * @param {string} yamlString - YAML formatted string (possibly encrypted)
+     * @param {Object} [options={}] - Conversion options
+     * @param {string} [options.conversionMode='no_encryption'] - Encryption mode
+     * @returns {string} TOON formatted string (possibly encrypted)
+     */
+    fromYaml(yamlString, options = {}) {
+        const { conversionMode = 'no_encryption' } = options;
+        return this._convertWithEncryption(yamlToToonSync, yamlString, conversionMode);
+    }
+
+    /**
+     * Convert YAML to TOON (Async, Instance Method)
+     * @param {string} yamlString - YAML formatted string (possibly encrypted)
+     * @param {Object} [options={}] - Conversion options
+     * @param {string} [options.conversionMode='no_encryption'] - Encryption mode
+     * @returns {Promise<string>} TOON formatted string (possibly encrypted)
+     */
+    async fromYamlAsync(yamlString, options = {}) {
+        const { conversionMode = 'no_encryption' } = options;
+        return this._convertWithEncryptionAsync(yamlToToon, yamlString, conversionMode);
+    }
+
+    /**
+     * Convert TOON to YAML (Sync, Instance Method)
+     * @param {string} toonString - TOON formatted string (possibly encrypted)
+     * @param {Object} [options={}] - Conversion options
+     * @param {string} [options.conversionMode='no_encryption'] - Encryption mode
+     * @returns {string} YAML formatted string
+     */
+    toYaml(toonString, options = {}) {
+        const { conversionMode = 'no_encryption' } = options;
+        return this._convertWithEncryption(toonToYamlSync, toonString, conversionMode);
+    }
+
+    /**
+     * Convert TOON to YAML (Async, Instance Method)
+     * @param {string} toonString - TOON formatted string (possibly encrypted)
+     * @param {Object} [options={}] - Conversion options
+     * @param {string} [options.conversionMode='no_encryption'] - Encryption mode
+     * @returns {Promise<string>} YAML formatted string
+     */
+    async toYamlAsync(toonString, options = {}) {
+        const { conversionMode = 'no_encryption' } = options;
+        return this._convertWithEncryptionAsync(toonToYaml, toonString, conversionMode);
+    }
+
+    /**
+     * Convert XML to TOON (Sync, Instance Method)
+     * @param {string} xmlString - XML formatted string (possibly encrypted)
+     * @param {Object} [options={}] - Conversion options
+     * @param {string} [options.conversionMode='no_encryption'] - Encryption mode
+     * @returns {string} TOON formatted string (possibly encrypted)
+     */
+    fromXml(xmlString, options = {}) {
+        const { conversionMode = 'no_encryption' } = options;
+        return this._convertWithEncryption(xmlToToonSync, xmlString, conversionMode);
+    }
+
+    /**
+     * Convert XML to TOON (Async, Instance Method)
+     * @param {string} xmlString - XML formatted string (possibly encrypted)
+     * @param {Object} [options={}] - Conversion options
+     * @param {string} [options.conversionMode='no_encryption'] - Encryption mode
+     * @returns {Promise<string>} TOON formatted string (possibly encrypted)
+     */
+    async fromXmlAsync(xmlString, options = {}) {
+        const { conversionMode = 'no_encryption' } = options;
+        return this._convertWithEncryptionAsync(xmlToToon, xmlString, conversionMode);
+    }
+
+    /**
+     * Convert TOON to XML (Sync, Instance Method)
+     * @param {string} toonString - TOON formatted string (possibly encrypted)
+     * @param {Object} [options={}] - Conversion options
+     * @param {string} [options.conversionMode='no_encryption'] - Encryption mode
+     * @returns {string} XML formatted string
+     */
+    toXml(toonString, options = {}) {
+        const { conversionMode = 'no_encryption' } = options;
+        return this._convertWithEncryption(toonToXmlSync, toonString, conversionMode);
+    }
+
+    /**
+     * Convert TOON to XML (Async, Instance Method)
+     * @param {string} toonString - TOON formatted string (possibly encrypted)
+     * @param {Object} [options={}] - Conversion options
+     * @param {string} [options.conversionMode='no_encryption'] - Encryption mode
+     * @returns {Promise<string>} XML formatted string
+     */
+    async toXmlAsync(toonString, options = {}) {
+        const { conversionMode = 'no_encryption' } = options;
+        return this._convertWithEncryptionAsync(toonToXml, toonString, conversionMode);
+    }
+
+    /**
+     * Convert CSV to TOON (Sync, Instance Method)
+     * @param {string} csvString - CSV formatted string (possibly encrypted)
+     * @param {Object} [options={}] - Conversion options
+     * @param {string} [options.conversionMode='no_encryption'] - Encryption mode
+     * @returns {string} TOON formatted string (possibly encrypted)
+     */
+    fromCsv(csvString, options = {}) {
+        const { conversionMode = 'no_encryption' } = options;
+        return this._convertWithEncryption(csvToToonSync, csvString, conversionMode);
+    }
+
+    /**
+     * Convert CSV to TOON (Async, Instance Method)
+     * @param {string} csvString - CSV formatted string (possibly encrypted)
+     * @param {Object} [options={}] - Conversion options
+     * @param {string} [options.conversionMode='no_encryption'] - Encryption mode
+     * @returns {Promise<string>} TOON formatted string (possibly encrypted)
+     */
+    async fromCsvAsync(csvString, options = {}) {
+        const { conversionMode = 'no_encryption' } = options;
+        return this._convertWithEncryptionAsync(csvToToon, csvString, conversionMode);
+    }
+
+    /**
+     * Convert TOON to CSV (Sync, Instance Method)
+     * @param {string} toonString - TOON formatted string (possibly encrypted)
+     * @param {Object} [options={}] - Conversion options
+     * @param {string} [options.conversionMode='no_encryption'] - Encryption mode
+     * @returns {string} CSV formatted string
+     */
+    toCsv(toonString, options = {}) {
+        const { conversionMode = 'no_encryption' } = options;
+        return this._convertWithEncryption(toonToCsvSync, toonString, conversionMode);
+    }
+
+    /**
+     * Convert TOON to CSV (Async, Instance Method)
+     * @param {string} toonString - TOON formatted string (possibly encrypted)
+     * @param {Object} [options={}] - Conversion options
+     * @param {string} [options.conversionMode='no_encryption'] - Encryption mode
+     * @returns {Promise<string>} CSV formatted string
+     */
+    async toCsvAsync(toonString, options = {}) {
+        const { conversionMode = 'no_encryption' } = options;
+        return this._convertWithEncryptionAsync(toonToCsv, toonString, conversionMode);
+    }
+
+    /**
+     * Validate a TOON string (Instance Method)
+     * Note: Validation does not support encryption modes
+     * @param {string} toonString - TOON formatted string to validate
+     * @returns {{isValid: boolean, error: string|null}} Validation result
+     */
+    validate(toonString) {
+        return validateToonStringSync(toonString);
+    }
+
+    /**
+     * Validate a TOON string (Async, Instance Method)
+     * Note: Validation does not support encryption modes
+     * @param {string} toonString - TOON formatted string to validate
+     * @returns {Promise<{isValid: boolean, error: string|null}>} Validation result
+     */
+    async validateAsync(toonString) {
+        return validateToonString(toonString);
+    }
+
+    // ========================================
+    // Static Methods (Backward Compatibility)
+    // ========================================
+
     /**
      * Convert JSON to TOON (Sync)
      * @param {*} jsonData - JSON data (object, array, or primitive)
@@ -58,21 +396,23 @@ export class ToonConverter {
     }
 
     /**
-     * Convert TOON to JSON (Sync)
+     * Convert TOON to JSON (Sync, Static Method)
      * @param {string} toonString - TOON formatted string
-     * @returns {*} Parsed JSON data
+     * @param {boolean} [returnJson=false] - If true, returns JSON string; if false, returns object
+     * @returns {*} Parsed JSON data (object or string)
      */
-    static toJson(toonString) {
-        return toonToJsonSync(toonString);
+    static toJson(toonString, returnJson = false) {
+        return toonToJsonSync(toonString, returnJson);
     }
 
     /**
-     * Convert TOON to JSON (Async)
+     * Convert TOON to JSON (Async, Static Method)
      * @param {string} toonString - TOON formatted string
-     * @returns {Promise<*>} Parsed JSON data
+     * @param {boolean} [returnJson=false] - If true, returns JSON string; if false, returns object
+     * @returns {Promise<*>} Parsed JSON data (object or string)
      */
-    static async toJsonAsync(toonString) {
-        return toonToJson(toonString);
+    static async toJsonAsync(toonString, returnJson = false) {
+        return toonToJson(toonString, returnJson);
     }
 
     /**

package/src/json.js

@@ -120,10 +120,11 @@ export async function jsonToToon(data) {
 /**
  * Converts TOON to JSON format (Synchronous)
  * @param {string} toonString - TOON formatted string
- * @returns {Object} JSON object
+ * @param {boolean} [returnJson=false] - If true, returns JSON string; if false, returns object
+ * @returns {Object|string} JSON object or JSON string
  * @throws {Error} If TOON string is invalid
  */
-export function toonToJsonSync(toonString) {
+export function toonToJsonSync(toonString, returnJson = false) {
     // Validate TOON string before conversion
     const validationStatus = validateToonStringSync(toonString);
     if (!validationStatus.isValid) {
@@ -136,7 +137,7 @@ export function toonToJsonSync(toonString) {
 
     // Pre-process: Check for Root Array or Root Primitive
     const firstLine = lines.find(l => l.trim() !== '');
-    if (!firstLine) return {}; // Empty document
+    if (!firstLine) return returnJson ? '{}' : {}; // Empty document
 
     // Root Array detection: [N]... at start of line
     if (firstLine.trim().startsWith('[')) {
@@ -324,14 +325,15 @@ export function toonToJsonSync(toonString) {
         }
     }
 
-    return root;
+    return returnJson ? JSON.stringify(root) : root;
 }
 
 /**
  * Converts TOON to JSON format (Async)
  * @param {string} toonString - TOON formatted string
- * @returns {Promise<Object>} Parsed JSON data
+ * @param {boolean} [returnJson=false] - If true, returns JSON string; if false, returns object
+ * @returns {Promise<Object|string>} Parsed JSON data (object or string)
  */
-export async function toonToJson(toonString) {
-    return toonToJsonSync(toonString);
+export async function toonToJson(toonString, returnJson = false) {
+    return toonToJsonSync(toonString, returnJson);
 }

package/.github/FUNDING.yml

@@ -1,15 +0,0 @@
-# These are supported funding model platforms
-
-github: [ankitpal181] # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
-# patreon: # Replace with a single Patreon username
-# open_collective: # Replace with a single Open Collective username
-# ko_fi: # Replace with a single Ko-fi username
-# tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
-# community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
-# liberapay: # Replace with a single Liberapay username
-# issuehunt: # Replace with a single IssueHunt username
-# lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
-# polar: # Replace with a single Polar username
-# buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
-# thanks_dev: # Replace with a single thanks.dev username
-# custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']