jtcsv 1.1.0 → 2.1.0

package/README.md

@@ -1,329 +1,286 @@
-# jtcsv - **The Complete JSON↔CSV Converter for Node.js**
+# jtcsv - Complete JSON ↔ CSV Converter
 
-⚡ **Zero dependencies** | 🚀 **Bidirectional Streaming** | 🖥️ **TUI Interface** | 🔄 **Complete API** | 🔒 **Security built-in** | 📊 **100% test coverage**
+**Version 2.0** - Now with full browser support, Web Workers, and streaming!
 
-## 🚀 Quick Start
+[![npm version](https://img.shields.io/npm/v/jtcsvps://www.npmjs.com/package/jtcsv)jtcsv
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)](https://www.npmjs.com/package/jtcsv
 
-### **Installation**
-```bash
-# Install globally with CLI and TUI support
-npm install -g jtcsv
+A lightweight, efficient, and secure library for converting between JSON and CSV formats with full browser support, Web Workers for large files, and streaming capabilities.
 
-# Or install locally in your project
-npm install jtcsv
-```
+## ✨ Features
 
-### **Basic Usage**
-```javascript
-const { jsonToCsv, csvToJson } = require('jtcsv');
+### 🚀 Core Features
+- **Bidirectional Conversion**: JSON ↔ CSV with full type preservation
+- **Zero Dependencies**: Pure JavaScript/TypeScript, no external dependencies
+- **TypeScript Support**: Full type definitions included
+- **Security First**: Built-in CSV injection protection
+- **RFC 4180 Compliant**: Proper CSV formatting and escaping
 
-// JSON → CSV
-const csv = jsonToCsv([{ id: 1, name: 'John' }], { delimiter: ',' });
+### 🌐 Browser Support
+- **Full Browser Compatibility**: Chrome, Firefox, Safari, Edge, Mobile
+- **Web Workers**: Process large files without blocking UI
+- **File API Integration**: Direct file upload/download support
+- **Streaming Processing**: Handle files of any size
+- **Progress Tracking**: Real-time progress updates
 
-// CSV → JSON  
-const json = csvToJson('id,name\\n1,John', { delimiter: ',' });
-```
+### ⚡ Performance
+- **High Speed**: Optimized parsing algorithms
+- **Memory Efficient**: Streaming and chunked processing
+- **Worker Pool**: Reusable Web Workers for parallel processing
+- **Caching**: Intelligent caching for repeated operations
 
-### **TUI Interface (Terminal UI)**
-```bash
-# Launch beautiful terminal interface
-jtcsv tui
+### 🔧 Advanced Features
+- **Auto-detection**: Automatic delimiter detection
+- **Custom Headers**: Flexible header mapping and renaming
+- **Nested Objects**: Support for complex nested structures
+- **Multiple Formats**: CSV, TSV, Excel-compatible output
+- **Error Handling**: Comprehensive error reporting and recovery
 
-# Or using npx
-npx jtcsv tui
-```
+## 📦 Installation
 
-### **CLI Commands**
+### Node.js
 ```bash
-# Convert JSON to CSV
-jtcsv json2csv input.json output.csv --delimiter=,
-
-# Convert CSV to JSON
-jtcsv csv2json input.csv output.json --parse-numbers
-
-# Streaming for large files
-jtcsv stream json2csv large.json output.csv --max-records=1000000
-
-# Show help
-jtcsv help
+npm install jtcsv
 ```
 
-## ✨ **What's New in v1.1.0**
-
-### 🎯 **Bidirectional Streaming API**
-- **JSON → CSV Streaming**: Process unlimited size files
-- **CSV → JSON Streaming**: Real-time parsing with backpressure
-- **Memory-efficient**: Constant memory usage regardless of file size
-- **Progress monitoring**: Real-time progress tracking
+### Browser (CDN)
+```html
+<!-- UMD version (global jtcsv variable) -->
+<script src="https://cdn.jsdelivr.net/npm/jtcsvst/jtcsv.umd.js"></script>
 
-### 🖥️ **Terminal User Interface (TUI)**
-- **Interactive interface**: No more command-line arguments
-- **Real-time preview**: See conversions as you type
-- **Multiple modes**: JSON→CSV, CSV→JSON, Batch processing, Settings
-- **Visual feedback**: Progress bars, status updates, color coding
-- **Keyboard shortcuts**: Efficient navigation for power users
+<!-- ESM version -->
+<script type="module">
+  import { jsonToCsv } from 'https://cdn.jsdelivr.net/npm/jtcsvst/jtcsv.esm.js';
+</script>
+```
 
-### 🔄 **Complete Streaming API**
+## 🚀 Quick Start
 
-#### **JSON to CSV Streaming**
+### Node.js Usage
 ```javascript
-const { createJsonToCsvStream, streamJsonToCsv } = require('jtcsv');
+const { jsonToCsv, csvToJson } = require('jtcsv
+
+// JSON to CSV
+const data = [
+  { id: 1, name: 'John', email: 'john@example.com' },
+  { id: 2, name: 'Jane', email: 'jane@example.com' }
+];
 
-// Create transform stream
-const transformStream = createJsonToCsvStream({
+const csv = jsonToCsv(data, {
   delimiter: ',',
   includeHeaders: true,
   preventCsvInjection: true
 });
 
-// Stream JSON objects to CSV
-await streamJsonToCsv(jsonStream, csvStream, options);
-```
+console.log(csv);
+// id,name,email
+// 1,John,john@example.com
+// 2,Jane,jane@example.com
 
-#### **CSV to JSON Streaming**
-```javascript
-const { createCsvToJsonStream, streamCsvToJson } = require('jtcsv');
-
-// Create transform stream  
-const transformStream = createCsvToJsonStream({
+// CSV to JSON
+const csvString = 'id,name,email\n1,John,john@example.com\n2,Jane,jane@example.com';
+const json = csvToJson(csvString, {
   delimiter: ',',
-  parseNumbers: true,
-  parseBooleans: true
+  parseNumbers: true
 });
 
-// Stream CSV text to JSON objects
-await streamCsvToJson(csvStream, jsonStream, options);
+console.log(json);
+// [
+//   { id: 1, name: 'John', email: 'john@example.com' },
+//   { id: 2, name: 'Jane', email: 'jane@example.com' }
+// ]
 ```
 
-### 🎨 **TUI Features**
-
-#### **Interactive Interface**
-```
-┌─────────────────────────────────────────────────────────────┐
-│ jtcsv - The Complete JSON↔CSV Converter                     │
-│ Press Ctrl+S to Save | Ctrl+P to Preview | Ctrl+Q to Quit   │
-├─────────────────────────────────────────────────────────────┤
-│ [JSON → CSV] [CSV → JSON] [Batch Process] [Settings]        │
-├─────────────────┬───────────────────────────────────────────┤
-│ JSON Input      │ CSV Output Preview                        │
-│ [              ]│ id,name,email                             │
-│ [              ]│ 1,John,john@example.com                   │
-│ [              ]│ 2,Jane,jane@example.com                   │
-├─────────────────┴───────────────────────────────────────────┤
-│ Options: Delimiter: , | Headers: ✓ | Parse Numbers: ✗      │
-├─────────────────────────────────────────────────────────────┤
-│ Ready to convert JSON to CSV                                │
-└─────────────────────────────────────────────────────────────┘
-```
-
-#### **TUI Navigation**
-| Shortcut | Action | Description |
-|----------|--------|-------------|
-| `Tab` | Switch elements | Move between UI components |
-| `Arrow Keys` | Navigate lists | Scroll through options |
-| `Enter` | Select/Activate | Choose option or confirm |
-| `Ctrl+S` | Save output | Save to file |
-| `Ctrl+P` | Preview | Show conversion preview |
-| `Ctrl+Q` | Quit | Exit application |
-| `Esc` | Back | Return to main mode |
-| `F1` | Help | Show help screen |
-
-## 📊 **Complete Feature Comparison**
-
-| Feature | jtcsv | PapaParse | csvtojson | json-2-csv |
-|---------|-------|-----------|-----------|------------|
-| **Size** | 8KB | 35KB | 45KB | 15KB |
-| **Dependencies** | 0 | 0 | 1 | 2 |
-| **JSON→CSV** | ✅ | ✅ | ❌ | ✅ |
-| **CSV→JSON** | ✅ | ✅ | ✅ | ✅ |
-| **Bidirectional Streaming** | ✅ | ⚠️ | ⚠️ | ❌ |
-| **TUI Interface** | ✅ | ❌ | ❌ | ❌ |
-| **CLI Tool** | ✅ | ❌ | ✅ | ✅ |
-| **CSV Injection Protection** | ✅ | ⚠️ | ❌ | ❌ |
-| **Path Traversal Protection** | ✅ | ❌ | ❌ | ❌ |
-| **TypeScript** | ✅ | ✅ | ⚠️ | ✅ |
-| **RFC 4180** | ✅ | ✅ | ✅ | ✅ |
-| **Zero Dependencies** | ✅ | ✅ | ❌ | ❌ |
-
-## 🚀 **Performance Benchmarks**
-
-### **Memory Usage**
-- **In-memory**: Up to 1 million records (configurable)
-- **Streaming**: Unlimited size with constant memory
-- **TUI**: < 50MB RAM for interface
-
-### **Processing Speed**
-```
-10,000 records: ~15ms
-100,000 records: ~120ms  
-1,000,000 records: ~1.2s
-Streaming 1GB file: ~45s (22MB/s)
-TUI response: < 100ms
-```
-
-### **Streaming Performance**
-- **Throughput**: 20-50MB/s depending on complexity
-- **Memory**: Constant ~10MB regardless of file size
-- **CPU**: Single-threaded, efficient parsing
-
-## 🛡️ **Enterprise-Grade Security**
-
-### **CSV Injection Protection**
-```javascript
-// Dangerous data is automatically escaped
-const dangerous = [
-  { formula: '=HYPERLINK(\"http://evil.com\",\"Click\")' },
-  { command: '@SUM(A1:A10)' }
-];
-
-const safeCsv = jsonToCsv(dangerous);
-// Formulas are prefixed with ' to prevent execution
-// Result: '=HYPERLINK(...) and '@SUM(A1:A10)
-```
-
-### **Path Traversal Protection**
-```javascript
-try {
-  // This will throw SecurityError
-  await saveAsCsv(data, '../../../etc/passwd.csv');
-} catch (error) {
-  console.error('Security violation:', error.message);
-}
-```
-
-### **Input Validation**
+### Browser Usage
 ```javascript
-// All inputs are strictly validated
-jsonToCsv('not an array'); // throws ValidationError
-jsonToCsv([], { delimiter: 123 }); // throws ConfigurationError
-jsonToCsv(largeArray, { maxRecords: 100 }); // throws LimitError if >100
-```
+// Using global variable (UMD)
+const csv = window.jtcsv.jsonToCsv(data, { delimiter: ',' });
 
-## 🔄 **Complete Streaming Examples**
-
-### **1. Large File Processing**
-```javascript
-const { createCsvFileToJsonStream } = require('jtcsv');
-const fs = require('fs');
+// Download as file
+window.jtcsv.downloadAsCsv(data, 'export.csv', { delimiter: ',' });
 
-// Process 10GB CSV file without loading into memory
-const jsonStream = await createCsvFileToJsonStream('./huge-data.csv', {
+// Parse uploaded file
+const fileInput = document.querySelector('input[type="file"]');
+const json = await window.jtcsv.parseCsvFile(fileInput.files[0], {
   delimiter: ',',
-  parseNumbers: true,
-  maxRows: Infinity // No limit for streaming
+  parseNumbers: true
 });
 
-// Pipe to database or another file
-jsonStream.pipe(databaseImportStream);
+// Use Web Workers for large files
+const largeFile = document.querySelector('input[type="file"]').files[0];
+const result = await window.jtcsv.parseCSVWithWorker(largeFile, {}, (progress) => {
+  console.log(`Progress: ${progress.percentage.toFixed(1)}%`);
+});
 ```
 
-### **2. Real-time Data Pipeline**
-```javascript
-const { createJsonToCsvStream } = require('jtcsv');
-
-// Create streaming pipeline
-const csvStream = createJsonToCsvStream({
-  delimiter: '|',
-  includeHeaders: true,
-  schema: {
-    properties: {
-      id: { type: 'integer' },
-      timestamp: { type: 'string', format: 'date-time' },
-      value: { type: 'number' }
+## 🔧 API Reference
+
+### Core Functions
+
+#### `jsonToCsv(data, options)`
+Converts an array of objects to CSV string.
+
+**Options:**
+- `delimiter` (string, default: ';'): CSV delimiter character
+- `includeHeaders` (boolean, default: true): Include header row
+- `renameMap` (object): Map for renaming column headers
+- `preventCsvInjection` (boolean, default: true): Escape formulas for security
+- `rfc4180Compliant` (boolean, default: true): RFC 4180 compliance
+- `maxRecords` (number): Maximum records to process
+
+#### `csvToJson(csv, options)`
+Converts CSV string to array of objects.
+
+**Options:**
+- `delimiter` (string): Delimiter (auto-detected if not specified)
+- `autoDetect` (boolean, default: true): Auto-detect delimiter
+- `hasHeaders` (boolean, default: true): CSV has header row
+- `parseNumbers` (boolean, default: false): Parse numeric values
+- `parseBooleans` (boolean, default: false): Parse boolean values
+- `trim` (boolean, default: true): Trim whitespace
+- `maxRows` (number): Maximum rows to process
+
+### Browser-Specific Functions
+
+#### `downloadAsCsv(data, filename, options)`
+Converts and downloads JSON as CSV file.
+
+#### `parseCsvFile(file, options)`
+Parses CSV File object to JSON.
+
+#### `createCsvBlob(data, options)`
+Creates CSV Blob without downloading.
+
+#### `parseCsvBlob(blob, options)`
+Parses CSV Blob to JSON.
+
+### Web Workers Functions
+
+#### `createWorkerPool(options)`
+Creates a pool of Web Workers for parallel processing.
+
+**Options:**
+- `workerCount` (number, default: 4): Number of workers
+- `maxQueueSize` (number, default: 100): Maximum queue size
+- `autoScale` (boolean, default: true): Auto-scale workers
+- `idleTimeout` (number, default: 60000): Idle timeout in ms
+
+#### `parseCSVWithWorker(csvInput, options, onProgress)`
+Parses CSV using Web Workers with progress tracking.
+
+## 💡 Examples
+
+### React Component Example
+```jsx
+import React, { useState } from 'react';
+import { parseCsvFile, downloadAsCsv } from 'jtcsv
+
+export function CSVProcessor() {
+  const [data, setData] = useState([]);
+  const [loading, setLoading] = useState(false);
+  
+  const handleFileUpload = async (event) => {
+    const file = event.target.files[0];
+    if (!file) return;
+    
+    setLoading(true);
+    try {
+      const jsonData = await parseCsvFile(file, {
+        delimiter: ',',
+        parseNumbers: true
+      });
+      setData(jsonData);
+    } catch (error) {
+      console.error('Error:', error);
+    } finally {
+      setLoading(false);
     }
-  }
-});
-
-// Connect to real-time data source
-websocketStream.pipe(csvStream).pipe(fileWriter);
+  };
+  
+  const handleExport = () => {
+    downloadAsCsv(data, 'export.csv', { delimiter: ',' });
+  };
+  
+  return (
+    <div>
+      <input type="file" accept=".csv" onChange={handleFileUpload} />
+      <button onClick={handleExport} disabled={!data.length}>
+        Export to CSV
+      </button>
+      {loading && <div>Processing...</div>}
+      <pre>{JSON.stringify(data.slice(0, 5), null, 2)}</pre>
+    </div>
+  );
+}
 ```
 
-### **3. Bidirectional Roundtrip**
+### Large File Processing with Progress
 ```javascript
-const { streamJsonToCsv, streamCsvToJson } = require('jtcsv');
-
-// JSON → CSV → JSON roundtrip with streaming
-await streamJsonToCsv(jsonStream, tempCsvStream, options);
-await streamCsvToJson(tempCsvStream, finalJsonStream, options);
-
-// Verify data integrity
-console.log('Roundtrip completed without data loss');
-```
-
-## 🖥️ **TUI Advanced Usage**
-
-### **Custom Configuration**
-```bash
-# Launch TUI with custom settings
-jtcsv tui --theme=dark --keymap=vim --locale=en-US
-```
-
-### **Batch Processing**
-```bash
-# Process all CSV files in directory
-jtcsv tui --batch --input-dir=./data --output-dir=./converted
-```
-
-### **Integration with Editors**
-```bash
-# Use TUI from within VSCode terminal
-# Or integrate with your favorite editor's terminal
+import { parseCSVWithWorker } from 'jtcsv
+
+async function processLargeFile(file) {
+  const progressBar = document.getElementById('progress-bar');
+  const status = document.getElementById('status');
+  
+  try {
+    const result = await parseCSVWithWorker(file, {}, (progress) => {
+      const percent = Math.round(progress.percentage);
+      progressBar.style.width = percent + '%';
+      progressBar.textContent = percent + '%';
+      
+      status.textContent = 
+        `Processing: ${progress.processed.toLocaleString()} of ${progress.total.toLocaleString()} rows ` +
+        `(${Math.round(progress.speed)} rows/sec)`;
+    });
+    
+    status.textContent = `Processed ${result.length.toLocaleString()} rows successfully`;
+    return result;
+  } catch (error) {
+    status.textContent = `Error: ${error.message}`;
+    throw error;
+  }
+}
 ```
 
-## 📦 **Project Structure**
+### Security: CSV Injection Protection
+```javascript
+const dangerousData = [
+  { formula: '=SUM(1,2)', command: '=cmd|"/c calc"!A1' }
+];
 
-```
-jtcsv/
-├── index.js              # Main entry point
-├── index.d.ts           # TypeScript definitions
-├── json-to-csv.js       # JSON→CSV conversion
-├── csv-to-json.js       # CSV→JSON conversion
-├── stream-json-to-csv.js # JSON→CSV streaming
-├── stream-csv-to-json.js # CSV→JSON streaming
-├── errors.js            # Error classes
-├── cli-tui.js           # Terminal User Interface
-├── bin/jtcsv.js         # CLI interface
-├── examples/            # Usage examples
-│   ├── streaming-example.js
-│   ├── express-api.js
-│   └── large-dataset-example.js
-├── __tests__/           # Test suites
-└── package.json
+// With protection enabled (default)
+const safeCsv = jsonToCsv(dangerousData, { preventCsvInjection: true });
+// formula,command
+// "'=SUM(1,2)","'=cmd|"/c calc"!A1"
+// Formulas are prefixed with single quote to prevent execution
+
+// Without protection
+const unsafeCsv = jsonToCsv(dangerousData, { preventCsvInjection: false });
+// formula,command
+// =SUM(1,2),=cmd|"/c calc"!A1
+// WARNING: This could execute commands in Excel!
 ```
 
-## 🎯 **When to Use jtcsv**
+## 📊 Performance
 
-### ✅ **Perfect For:**
-- **Enterprise applications** requiring security
-- **Large file processing** (>100MB)
-- **Real-time data pipelines**
-- **Terminal/CLI workflows**
-- **TypeScript projects**
-- **Embedded systems** (zero dependencies)
-- **Batch processing** automation
-- **Data migration** tools
+### Benchmark Results
 
-### ⚠️ **Consider Alternatives For:**
-- **Browser-only applications** (use PapaParse)
-- **Extremely simple conversions** (use built-in methods)
-- **Specialized CSV formats** with complex requirements
+| File Size | Rows | Without Workers | With Workers | Improvement |
+|-----------|------|-----------------|--------------|-------------|
+| 1 MB      | 10K  | 120 ms          | 80 ms        | 33% faster  |
+| 10 MB     | 100K | 1.2 sec         | 0.8 sec      | 33% faster  |
+| 100 MB    | 1M   | 12 sec          | 7 sec        | 42% faster  |
+| 500 MB    | 5M   | 65 sec          | 35 sec       | 46% faster  |
 
-## 🔧 **Development**
+### Memory Usage
+- **Without streaming**: Loads entire file into memory
+- **With streaming**: Processes in chunks (default 10K rows)
+- **With Web Workers**: Distributes memory across workers
 
-### **Running Tests**
-```bash
-# Run all tests
-npm test
-
-# Test with coverage
-npm run test:coverage
-
-# Run specific test suites
-npm test -- --testPathPattern=streaming
-npm test -- --testPathPattern=tui
-```
+## 🛠️ Development
 
-### **Building from Source**
+### Building from Source
 ```bash
 # Clone repository
 git clone https://github.com/Linol-Hamelton/jtcsv.git
@@ -332,62 +289,63 @@ cd jtcsv
 # Install dependencies
 npm install
 
-# Run TUI for development
-npm run tui
+# Build browser version
+npm run build
 
-# Test CLI
-npm run cli help
+# Run tests
+npm test
+
+# Start demo server
+npm run demo
+```
+
+### Project Structure
+```
+jtcsv/
+├── src/browser/           # Browser-specific code
+│   ├── index.js          # Browser entry point
+│   ├── *.js              # Browser modules
+│   └── workers/          # Web Workers implementation
+├── dist/                 # Built distributions
+│   ├── jtcsv.umd.js     # UMD bundle
+│   ├── jtcsv.esm.js     # ESM bundle
+│   └── jtcsv.cjs.js     # CJS bundle
+├── demo/                 # Demo application
+├── __tests__/           # Test files
+├── rollup.config.mjs     # Build configuration
+└── package.json         # Project configuration
 ```
 
-## 🤝 **Contributing**
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
 
 1. Fork the repository
-2. Create a feature branch
-3. Add tests for new functionality
-4. Ensure all tests pass: `npm test`
-5. Submit a Pull Request
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
 
-### **Development Guidelines**
-- Maintain 100% test coverage
-- Follow existing code style
-- Add TypeScript definitions for new features
-- Update documentation
-- Consider security implications
+## 📄 License
 
-## 📄 **License**
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
-MIT © Ruslan Fomenko
+## 🙏 Acknowledgments
 
-## 🔗 **Links**
+- Inspired by the need for secure, efficient CSV processing in browsers
+- Thanks to all contributors who have helped improve this library
+- Special thanks to the open source community for invaluable tools and libraries
 
-- **GitHub**: https://github.com/Linol-Hamelton/jtcsv
-- **npm**: https://www.npmjs.com/package/jtcsv
-- **Issues**: https://github.com/Linol-Hamelton/jtcsv/issues
-- **TUI Documentation**: ./TUI-README.md
+## 📞 Support
 
----
+- **GitHub Issues**: [Report bugs or request features](https://github.com/Linol-Hamelton/jtcsv/issues)
+- **Documentation**: [Full API documentation](https://github.com/Linol-Hamelton/jtcsv#readme)
+- **Examples**: [Example code and demos](https://github.com/Linol-Hamelton/jtcsv/tree/main/demo)
 
-## 🏆 **Why jtcsv Stands Out**
+---
 
-### **Unique Selling Points**
-1. **Zero Dependencies** - Perfect for production and embedded use
-2. **Bidirectional Streaming** - Handle files of any size
-3. **TUI Interface** - User-friendly terminal experience
-4. **Enterprise Security** - Built-in protection against attacks
-5. **Complete Solution** - From simple conversions to complex pipelines
+**Happy coding!** If you find this library useful, please consider giving it a star on GitHub ⭐
 
-### **Competitive Advantage**
-- **vs PapaParse**: Better security, TUI interface, zero dependencies
-- **vs csvtojson**: Bidirectional conversion, streaming, security
-- **vs json-2-csv**: Streaming API, TUI, better performance
 
-### **Future Roadmap**
-- **Plugin system** for extended functionality
-- **Web interface** for browser-based usage
-- **Database connectors** for direct import/export
-- **Cloud integration** for serverless workflows
-- **Machine learning** for automatic schema detection
 
----
 
-**Ready for production with enterprise-grade features and unmatched flexibility.**