`\n\nSaves a JavaScript object as a BuuD file with optional comments.\n\n```javascript\nconst userData = {\n users: [\n { id: 1, name: \"Alice\", active: true },\n { id: 2, name: \"Bob\", active: false }\n ],\n lastUpdate: new Date().toISOString()\n};\n\n// Save with comments\nawait buuDATA.file.save('./users.buud', userData, [\n \"User database\",\n \"Last modified: \" + new Date().toLocaleDateString()\n]);\n\n// Save without comments\nawait buuDATA.file.save('./data.buud', userData);\n```\n\n**Parameters:**\n- `filePath` (string): Destination file path\n- `data` (any): JavaScript object to save\n- `comments` (string|string[], optional): Header comments\n\n**Returns:** Promise that resolves when file is saved\n\n## ⚡ Advanced Usage\n\n### Configuration Management\n```javascript\nconst { buuDATA } = require('@buudata/buudata');\n\nclass ConfigManager {\n constructor(configPath) {\n this.configPath = configPath;\n }\n \n async load() {\n try {\n this.config = await buuDATA.file.load(this.configPath);\n return this.config;\n } catch (error) {\n // Return default config if file doesn't exist\n this.config = this.getDefaultConfig();\n await this.save();\n return this.config;\n }\n }\n \n async save() {\n const comments = [\n \"Application Configuration\",\n \"Auto-generated on: \" + new Date().toISOString(),\n \"Modify with caution!\"\n ];\n \n await buuDATA.file.save(this.configPath, this.config, comments);\n }\n \n get(key) {\n return this.config[key];\n }\n \n set(key, value) {\n this.config[key] = value;\n }\n \n getDefaultConfig() {\n return {\n version: \"1.0.0\",\n debug: false,\n server: {\n host: \"localhost\",\n port: 3000\n },\n database: {\n host: \"localhost\",\n port: 5432,\n name: \"myapp\"\n }\n };\n }\n}\n\n// Usage\nasync function main() {\n const config = new ConfigManager('./app.buud');\n await config.load();\n \n console.log('Server port:', config.get('server').port);\n \n // Update configuration\n config.set('debug', true);\n await config.save();\n}\n\nmain();\n```\n\n### Data Processing Pipeline\n```javascript\nconst { buuDATA } = require('@buudata/buudata');\nconst path = require('path');\n\nclass DataProcessor {\n constructor(inputDir, outputDir) {\n this.inputDir = inputDir;\n this.outputDir = outputDir;\n }\n \n async processFile(filename) {\n const inputPath = path.join(this.inputDir, filename);\n const outputPath = path.join(this.outputDir, filename.replace('.buud', '.json'));\n \n try {\n // Load BuuD file\n const data = await buuDATA.file.load(inputPath);\n \n // Process data (example: add timestamp)\n data.processedAt = new Date().toISOString();\n data.processor = \"BuuData v1.0.0\";\n \n // Save as standard JSON\n const fs = require('fs/promises');\n await fs.writeFile(outputPath, JSON.stringify(data, null, 2));\n \n console.log(`✅ Processed: ${filename}`);\n return data;\n } catch (error) {\n console.error(`❌ Error processing ${filename}:`, error.message);\n throw error;\n }\n }\n \n async processDirectory() {\n const fs = require('fs/promises');\n const files = await fs.readdir(this.inputDir);\n const buudFiles = files.filter(f => f.endsWith('.buud'));\n \n console.log(`📁 Processing ${buudFiles.length} BuuD files...`);\n \n const results = [];\n for (const file of buudFiles) {\n const result = await this.processFile(file);\n results.push(result);\n }\n \n return results;\n }\n}\n\n// Usage\nasync function batchProcess() {\n const processor = new DataProcessor('./input', './output');\n const results = await processor.processDirectory();\n console.log(`🎉 Processed ${results.length} files successfully!`);\n}\n\nbatchProcess();\n```\n\n### Database-like File Operations\n```javascript\nconst { buuDATA } = require('@buudata/buudata');\n\nclass BuuDatabase {\n constructor(filePath) {\n this.filePath = filePath;\n this.data = { records: [], metadata: {} };\n }\n \n async initialize() {\n try {\n this.data = await buuDATA.file.load(this.filePath);\n } catch (error) {\n // Create new database file\n this.data = {\n records: [],\n metadata: {\n version: \"1.0.0\",\n created: new Date().toISOString(),\n lastModified: new Date().toISOString()\n }\n };\n await this.save();\n }\n }\n \n async save() {\n this.data.metadata.lastModified = new Date().toISOString();\n \n const comments = [\n \"BuuDatabase File\",\n \"Records: \" + this.data.records.length,\n \"Last Modified: \" + new Date().toLocaleString()\n ];\n \n await buuDATA.file.save(this.filePath, this.data, comments);\n }\n \n async insert(record) {\n const id = this.data.records.length + 1;\n const newRecord = {\n id,\n ...record,\n createdAt: new Date().toISOString()\n };\n \n this.data.records.push(newRecord);\n await this.save();\n return newRecord;\n }\n \n find(query) {\n return this.data.records.filter(record => {\n return Object.keys(query).every(key => record[key] === query[key]);\n });\n }\n \n findById(id) {\n return this.data.records.find(record => record.id === id);\n }\n \n async update(id, updates) {\n const record = this.findById(id);\n if (!record) throw new Error(`Record with id ${id} not found`);\n \n Object.assign(record, updates, { updatedAt: new Date().toISOString() });\n await this.save();\n return record;\n }\n \n async delete(id) {\n const index = this.data.records.findIndex(record => record.id === id);\n if (index === -1) throw new Error(`Record with id ${id} not found`);\n \n const deleted = this.data.records.splice(index, 1)[0];\n await this.save();\n return deleted;\n }\n \n count() {\n return this.data.records.length;\n }\n \n all() {\n return [...this.data.records];\n }\n}\n\n// Usage\nasync function databaseExample() {\n const db = new BuuDatabase('./users.buud');\n await db.initialize();\n \n // Insert users\n const user1 = await db.insert({ name: \"Alice\", email: \"alice@example.com\" });\n const user2 = await db.insert({ name: \"Bob\", email: \"bob@example.com\" });\n \n console.log('Inserted users:', user1, user2);\n \n // Query users\n const allUsers = db.all();\n console.log('All users:', allUsers);\n \n // Find specific user\n const alice = db.find({ name: \"Alice\" });\n console.log('Found Alice:', alice);\n \n // Update user\n await db.update(user1.id, { email: \"alice.updated@example.com\" });\n \n // Count records\n console.log('Total users:', db.count());\n \n // Delete user\n await db.delete(user2.id);\n console.log('Remaining users:', db.count());\n}\n\ndatabaseExample();\n```\n\n## 🛡️ Error Handling\n\n```javascript\nconst { buuDATA } = require('@buudata/buudata');\n\nasync function robustExample() {\n try {\n // Handle invalid input type\n buuDATA.parse(123); // Throws TypeError\n } catch (error) {\n if (error instanceof TypeError) {\n console.log('Invalid input type:', error.message);\n }\n }\n \n try {\n // Handle invalid JSON\n buuDATA.parse('{ invalid json }'); // Throws SyntaxError\n } catch (error) {\n if (error instanceof SyntaxError) {\n console.log('Invalid JSON syntax:', error.message);\n }\n }\n \n try {\n // Handle file not found\n await buuDATA.file.load('./nonexistent.buud');\n } catch (error) {\n if (error.code === 'ENOENT') {\n console.log('File not found, creating default...');\n const defaultData = { initialized: true };\n await buuDATA.file.save('./nonexistent.buud', defaultData);\n }\n }\n \n try {\n // Handle permission errors\n await buuDATA.file.save('/root/restricted.buud', {});\n } catch (error) {\n if (error.code === 'EACCES') {\n console.log('Permission denied, trying alternative location...');\n await buuDATA.file.save('./restricted.buud', {});\n }\n }\n}\n\nrobustExample();\n```\n\n## 🎯 Use Cases\n\n**Perfect for:**\n- 🔧 **Configuration Files** - App settings with inline documentation\n- 📊 **Data Storage** - Lightweight JSON database with comments\n- 🗃️ **File-based Databases** - Simple record storage\n- 📝 **Documentation** - Self-documenting data files\n- ⚙️ **Build Configurations** - Commented build settings\n- 🎮 **Game Data** - Level configurations with notes\n- 📋 **Form Schemas** - UI form definitions with explanations\n- 🌐 **API Configurations** - Endpoint settings with descriptions\n\n## 🔍 Technical Details\n\n\n\n- ✅ **Node.js Core Only** - fs/promises, path modules\n- ✅ **CommonJS Module** - Standard require() syntax\n- ✅ **Zero Dependencies** - No external packages required\n- ✅ **Comment Regex** - Handles both `//` and `/* */` styles\n- ✅ **Error Safe** - Comprehensive error handling\n- ✅ **Path Resolution** - Absolute path conversion\n- ✅ **UTF-8 Encoding** - Full Unicode support\n- ✅ **Memory Efficient** - Minimal memory footprint\n- ✅ **Cross-Platform** - Works on Windows, macOS, Linux\n\n
\n\n## 📋 Package Contents\n\n- 📃 `src/index.js` - Main BuuData library\n- 📜 `package.json` - Package configuration\n- 📖 `README.md` - This comprehensive documentation\n\n## 🤝 Contributing\n\nWe welcome contributions! You can:\n\n- 🐛 Report bugs and issues\n- 💡 Suggest new features and improvements\n- 🔧 Submit pull requests\n- 📖 Improve documentation\n- 🌟 Rate and share the package\n\n## 📄 License\n\n\n\n**MIT License** - Free and Open Source\n\nThis project is licensed under the MIT License, which means you are free to:\n- ✅ *Use* - Use this library in personal and commercial projects\n- ✅ *Modify* - Change and customize the code to fit your needs \n- ✅ *Distribute* - Share and redistribute the library\n- ✅ *Private Use* - Use in private projects without restrictions\n- ✅ *Commercial Use* - Use in commercial applications and products\n\nThe only requirement is to include the original copyright notice and license terms.\n\n
\n\n## 🌐 Connect with Us\n\n\n\n---\n\n\n
\n Made with 💜 by HonneyBuuModz\n
\n \n
\n 🌟 If this project helped you, please consider giving it a star! 🌟\n
\n
\n
![\"Built](\"https://img.shields.io/badge/Built_with-💜_and_🍁-8A2BE2?style=for-the-badge&labelColor=1a1a1a\")
\n
![\"Version\"](\"https://img.shields.io/badge/Version-V1.0.0-ff6b6b?style=for-the-badge&logo=tag&logoColor=white&labelColor=1a1a1a\"){kind=icon}
\n ![\"BuuData\"](\"https://img.shields.io/badge/buu--data-Library-8A2BE2?style=for-the-badge&logo=javascript&logoColor=white&labelColor=1a1a1a\"){kind=icon}
\n ![\"NPM](\"https://img.shields.io/badge/NPM-Package-DA70D6?style=for-the-badge&logo=npm&logoColor=white&labelColor=1a1a1a\"){kind=icon}
\n ![\"License\"](\"https://img.shields.io/badge/License-MIT-9370DB?style=for-the-badge&labelColor=1a1a1a\"){kind=icon}
\n ![\"JavaScript](\"https://img.shields.io/badge/JavaScript-F7DF1E?style=for-the-badge&logo=javascript&logoColor=white&labelColor=1a1a1a\"){kind=icon}
\n