jtcsv 1.1.0 → 1.2.0

package/README.md

@@ -1,187 +1,242 @@
-# jtcsv - **The Complete JSON↔CSV Converter for Node.js**
+"# jtcsv - **The Complete JSON↔CSV Converter for Node.js**
 
-⚡ **Zero dependencies** | 🚀 **Bidirectional Streaming** | 🖥️ **TUI Interface** | 🔄 **Complete API** | 🔒 **Security built-in** | 📊 **100% test coverage**
+⚡ **Zero dependencies** | 🚀 **Streaming for large files** | 🔄 **Bidirectional conversion** | 🔒 **Security built-in** | 📊 **100% test coverage**
 
 ## 🚀 Quick Start
 
-### **Installation**
-```bash
-# Install globally with CLI and TUI support
-npm install -g jtcsv
-
-# Or install locally in your project
-npm install jtcsv
+### JSON → CSV
+```javascript
+const { jsonToCsv } = require('jtcsv');
+
+const csv = jsonToCsv([
+  { id: 1, name: 'John Doe' },
+  { id: 2, name: 'Jane Smith' }
+], { delimiter: ',' });
+
+console.log(csv);
+// Output:
+// id,name
+// 1,John Doe
+// 2,Jane Smith
 ```
 
-### **Basic Usage**
+### CSV → JSON
 ```javascript
-const { jsonToCsv, csvToJson } = require('jtcsv');
+const { csvToJson } = require('jtcsv');
 
-// JSON → CSV
-const csv = jsonToCsv([{ id: 1, name: 'John' }], { delimiter: ',' });
+// Auto-detect delimiter (no need to specify)
+const csv = 'id,name\\n1,John\\n2,Jane';
+const json = csvToJson(csv); // Automatically detects comma delimiter
 
-// CSV → JSON  
-const json = csvToJson('id,name\\n1,John', { delimiter: ',' });
-```
+console.log(json);
+// Output: [{id: '1', name: 'John'}, {id: '2', name: 'Jane'}]
 
-### **TUI Interface (Terminal UI)**
-```bash
-# Launch beautiful terminal interface
-jtcsv tui
+// Works with any delimiter
+const csvSemicolon = 'id;name;email\\n1;John;john@example.com';
+const json2 = csvToJson(csvSemicolon); // Automatically detects semicolon
 
-# Or using npx
-npx jtcsv tui
+// Disable auto-detect if needed
+const csvCustom = 'id|name|age\\n1|John|30';
+const json3 = csvToJson(csvCustom, { 
+  delimiter: '|', 
+  autoDetect: false 
+});
 ```
 
-### **CLI Commands**
+## 📦 Installation
+
 ```bash
-# Convert JSON to CSV
-jtcsv json2csv input.json output.csv --delimiter=,
+npm install jtcsv
+```
 
-# Convert CSV to JSON
-jtcsv csv2json input.csv output.json --parse-numbers
+## ✨ Key Features
 
-# Streaming for large files
-jtcsv stream json2csv large.json output.csv --max-records=1000000
+### ✅ **Complete JSON↔CSV Conversion**
+- **JSON → CSV**: Convert arrays of objects to CSV format
+- **CSV → JSON**: Parse CSV strings back to JSON arrays
+- **File Operations**: Read/write CSV files with security validation
 
-# Show help
-jtcsv help
-```
+### ✅ **Streaming API for Large Files**
+- Process files >100MB without loading into memory
+- Real-time transformation with backpressure handling
+- Schema validation during streaming
 
-## ✨ **What's New in v1.1.0**
+### ✅ **Enterprise-Grade Security**
+- **CSV Injection Protection**: Automatic escaping of Excel formulas
+- **Path Traversal Protection**: Safe file path validation
+- **Input Validation**: Type checking and size limits
 
-### 🎯 **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
+### ✅ **Performance Optimized**
+- Zero dependencies, ~8KB package size
+- Memory-efficient streaming
+- RFC 4180 compliant output
 
-### 🖥️ **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
+### ✅ **TypeScript Ready**
+- Full TypeScript definitions included
+- IntelliSense support in modern editors
 
-### 🔄 **Complete Streaming API**
+## 📊 Real-World Examples
 
-#### **JSON to CSV Streaming**
+### 1. Database Export to CSV
 ```javascript
-const { createJsonToCsvStream, streamJsonToCsv } = require('jtcsv');
+const { saveAsCsv } = require('jtcsv');
 
-// Create transform stream
-const transformStream = createJsonToCsvStream({
+// Export users from database
+const users = await db.query('SELECT * FROM users');
+await saveAsCsv(users, './exports/users.csv', {
   delimiter: ',',
-  includeHeaders: true,
-  preventCsvInjection: true
+  renameMap: {
+    id: 'User ID',
+    email: 'Email Address',
+    created_at: 'Registration Date'
+  }
 });
-
-// Stream JSON objects to CSV
-await streamJsonToCsv(jsonStream, csvStream, options);
 ```
 
-#### **CSV to JSON Streaming**
+### 2. CSV Import to Database
 ```javascript
-const { createCsvToJsonStream, streamCsvToJson } = require('jtcsv');
+const { readCsvAsJson } = require('jtcsv');
 
-// Create transform stream  
-const transformStream = createCsvToJsonStream({
+// Import users from CSV file
+const users = await readCsvAsJson('./imports/users.csv', {
   delimiter: ',',
   parseNumbers: true,
   parseBooleans: true
 });
 
-// Stream CSV text to JSON objects
-await streamCsvToJson(csvStream, jsonStream, options);
+await db.insert('users', users);
 ```
 
-### 🎨 **TUI Features**
+### 3. Streaming Large Dataset
+```javascript
+const { createJsonToCsvStream, saveJsonStreamAsCsv } = require('./stream-json-to-csv.js');
+const fs = require('fs');
 
-#### **Interactive Interface**
+// Process 1GB JSON file without loading into memory
+const jsonStream = fs.createReadStream('./large-data.jsonl', 'utf8');
+await saveJsonStreamAsCsv(jsonStream, './output.csv', {
+  delimiter: ','
+});
 ```
-┌─────────────────────────────────────────────────────────────┐
-│ 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                                │
-└─────────────────────────────────────────────────────────────┘
+
+### 4. API Response Conversion
+```javascript
+const { jsonToCsv } = require('jtcsv');
+
+// Convert API response to downloadable CSV
+app.get('/api/users/export', async (req, res) => {
+  const users = await fetchUsersFromAPI();
+  const csv = jsonToCsv(users, {
+    delimiter: ',',
+    preventCsvInjection: true,
+    rfc4180Compliant: true
+  });
+  
+  res.setHeader('Content-Type', 'text/csv');
+  res.setHeader('Content-Disposition', 'attachment; filename=\"users.csv\"');
+  res.send(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** | ✅ | ✅ | ❌ | ❌ |
+## 🔧 API Reference
 
-## 🚀 **Performance Benchmarks**
+### Core Functions
 
-### **Memory Usage**
-- **In-memory**: Up to 1 million records (configurable)
-- **Streaming**: Unlimited size with constant memory
-- **TUI**: < 50MB RAM for interface
+#### `jsonToCsv(data, options)`
+Convert JSON array to CSV string.
 
-### **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
+**Options:**
+- `delimiter` (default: ';') - CSV delimiter character
+- `includeHeaders` (default: true) - Include headers row
+  - `renameMap` - Rename column headers `{ oldKey: newKey }`
+  - `template` - Ensure consistent column order
+  - `maxRecords` (optional) - Maximum records to process (no limit by default)
+  - `preventCsvInjection` (default: true) - Escape Excel formulas
+  - `rfc4180Compliant` (default: true) - RFC 4180 compliance
+
+#### `csvToJson(csv, options)`
+Convert CSV string to JSON array.
+
+**Options:**
+- `delimiter` (default: auto-detected) - CSV delimiter character
+- `autoDetect` (default: true) - Auto-detect delimiter if not specified
+- `candidates` (default: [';', ',', '\t', '|']) - Candidate delimiters for auto-detection
+- `hasHeaders` (default: true) - CSV has headers row
+- `renameMap` - Rename column headers `{ newKey: oldKey }`
+- `parseNumbers` (default: false) - Parse numeric values
+- `parseBooleans` (default: false) - Parse boolean values
+- `maxRows` (optional) - Maximum rows to process (no limit by default)
+
+#### `autoDetectDelimiter(csv, candidates)`
+Auto-detect CSV delimiter from content.
+
+**Parameters:**
+- `csv` - CSV content string
+- `candidates` (optional) - Array of candidate delimiters (default: [';', ',', '\t', '|'])
+
+**Returns:** Detected delimiter string
+
+**Example:**
+```javascript
+const { autoDetectDelimiter } = require('jtcsv');
+
+const delimiter = autoDetectDelimiter('id,name,age\\n1,John,30');
+console.log(delimiter); // Output: ','
 ```
 
-### **Streaming Performance**
-- **Throughput**: 20-50MB/s depending on complexity
-- **Memory**: Constant ~10MB regardless of file size
-- **CPU**: Single-threaded, efficient parsing
+#### `saveAsCsv(data, filePath, options)`
+Save JSON data as CSV file with security validation.
+
+#### `readCsvAsJson(filePath, options)`
+Read CSV file and convert to JSON array.
+
+#### `readCsvAsJsonSync(filePath, options)`
+Synchronous version of `readCsvAsJson`.
 
-## 🛡️ **Enterprise-Grade Security**
+### Streaming API (stream-json-to-csv.js)
 
-### **CSV Injection Protection**
+#### `createJsonToCsvStream(options)`
+Create transform stream for JSON→CSV conversion.
+
+#### `streamJsonToCsv(inputStream, outputStream, options)`
+Pipe JSON stream through CSV transformation.
+
+#### `saveJsonStreamAsCsv(inputStream, filePath, options)`
+Stream JSON to CSV file.
+
+#### `createJsonReadableStream(data)`
+Create readable stream from JSON array.
+
+#### `createCsvCollectorStream()`
+Create writable stream that collects CSV data.
+
+### Error Handling
+
+Custom error classes for better debugging:
+- `JtcsvError` - Base error class
+- `ValidationError` - Input validation errors
+- `SecurityError` - Security violations
+- `FileSystemError` - File system operations
+- `ParsingError` - CSV/JSON parsing errors
+- `LimitError` - Size limit exceeded
+- `ConfigurationError` - Invalid configuration
+
+## 🛡️ Security Features
+
+### CSV Injection Protection
 ```javascript
-// Dangerous data is automatically escaped
+// Dangerous data with Excel formulas
 const dangerous = [
-  { formula: '=HYPERLINK(\"http://evil.com\",\"Click\")' },
-  { command: '@SUM(A1:A10)' }
+  { id: 1, formula: '=HYPERLINK(\"http://evil.com\",\"Click\")' },
+  { id: 2, formula: '@IMPORTANT' }
 ];
 
+// Automatically escaped
 const safeCsv = jsonToCsv(dangerous);
 // Formulas are prefixed with ' to prevent execution
-// Result: '=HYPERLINK(...) and '@SUM(A1:A10)
 ```
 
-### **Path Traversal Protection**
+### Path Traversal Protection
 ```javascript
 try {
   // This will throw SecurityError
@@ -191,86 +246,81 @@ try {
 }
 ```
 
-### **Input Validation**
+### Input Validation
 ```javascript
-// All inputs are strictly validated
+// All inputs are validated
 jsonToCsv('not an array'); // throws ValidationError
 jsonToCsv([], { delimiter: 123 }); // throws ConfigurationError
-jsonToCsv(largeArray, { maxRecords: 100 }); // throws LimitError if >100
+jsonToCsv(largeArray, { maxRecords: 100 }); // throws LimitError if >100 records
+```
+
+## 📈 Performance
+
+### Memory Efficiency
+- **In-memory**: Unlimited records (with performance warning for >1M)
+- **Streaming**: Unlimited size with constant memory
+- **Zero-copy**: Efficient buffer management
+
+### Benchmark Results
+```
+10,000 records: ~15ms
+100,000 records: ~120ms
+1,000,000 records: ~1.2s
+Streaming 1GB file: ~45s (22MB/s)
 ```
 
-## 🔄 **Complete Streaming Examples**
+## 🔄 Complete Roundtrip Example
 
-### **1. Large File Processing**
 ```javascript
-const { createCsvFileToJsonStream } = require('jtcsv');
-const fs = require('fs');
+const { jsonToCsv, csvToJson } = require('jtcsv');
 
-// Process 10GB CSV file without loading into memory
-const jsonStream = await createCsvFileToJsonStream('./huge-data.csv', {
+// Original data
+const original = [
+  { id: 1, name: 'John', active: true, score: 95.5 },
+  { id: 2, name: 'Jane', active: false, score: 88.0 }
+];
+
+// Convert to CSV
+const csv = jsonToCsv(original, {
   delimiter: ',',
   parseNumbers: true,
-  maxRows: Infinity // No limit for streaming
+  parseBooleans: true
 });
 
-// Pipe to database or another file
-jsonStream.pipe(databaseImportStream);
-```
-
-### **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' }
-    }
-  }
+// Convert back to JSON
+const restored = csvToJson(csv, {
+  delimiter: ',',
+  parseNumbers: true,
+  parseBooleans: true
 });
 
-// Connect to real-time data source
-websocketStream.pipe(csvStream).pipe(fileWriter);
+// restored is identical to original
+console.assert(JSON.stringify(original) === JSON.stringify(restored));
 ```
 
-### **3. Bidirectional Roundtrip**
-```javascript
-const { streamJsonToCsv, streamCsvToJson } = require('jtcsv');
+## 🧪 Testing
 
-// JSON → CSV → JSON roundtrip with streaming
-await streamJsonToCsv(jsonStream, tempCsvStream, options);
-await streamCsvToJson(tempCsvStream, finalJsonStream, options);
+```bash
+# Run all tests (108 tests)
+npm test
 
-// Verify data integrity
-console.log('Roundtrip completed without data loss');
-```
+# Test with coverage
+npm run test:coverage
 
-## 🖥️ **TUI Advanced Usage**
+# Run specific test suites
+npm test -- --testPathPattern=csv-to-json
+npm test -- --testPathPattern=stream
 
-### **Custom Configuration**
-```bash
-# Launch TUI with custom settings
-jtcsv tui --theme=dark --keymap=vim --locale=en-US
-```
+# Lint code
+npm run lint
 
-### **Batch Processing**
-```bash
-# Process all CSV files in directory
-jtcsv tui --batch --input-dir=./data --output-dir=./converted
+# Security audit
+npm run security-check
 ```
 
-### **Integration with Editors**
-```bash
-# Use TUI from within VSCode terminal
-# Or integrate with your favorite editor's terminal
-```
+**Test Coverage: 100%** (108 passing tests)
 
-## 📦 **Project Structure**
+## 📁 Project Structure
 
 ```
 jtcsv/
@@ -278,68 +328,51 @@ jtcsv/
 ├── 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
+├── stream-json-to-csv.js # Streaming API
 ├── examples/            # Usage examples
-│   ├── streaming-example.js
-│   ├── express-api.js
+│   ├── express-api.js   # Express server example
+│   ├── cli-tool.js      # Command line tool
 │   └── large-dataset-example.js
 ├── __tests__/           # Test suites
 └── package.json
 ```
 
-## 🎯 **When to Use jtcsv**
-
-### ✅ **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
+## 🚀 Getting Started
 
-### ⚠️ **Consider Alternatives For:**
-- **Browser-only applications** (use PapaParse)
-- **Extremely simple conversions** (use built-in methods)
-- **Specialized CSV formats** with complex requirements
+### Basic Usage
+```javascript
+const jtcsv = require('jtcsv');
 
-## 🔧 **Development**
+// Convert JSON to CSV
+const csv = jtcsv.jsonToCsv(data);
 
-### **Running Tests**
-```bash
-# Run all tests
-npm test
+// Convert CSV to JSON
+const json = jtcsv.csvToJson(csv);
 
-# Test with coverage
-npm run test:coverage
+// Save to file
+await jtcsv.saveAsCsv(data, 'output.csv');
 
-# Run specific test suites
-npm test -- --testPathPattern=streaming
-npm test -- --testPathPattern=tui
+// Read from file
+const data = await jtcsv.readCsvAsJson('input.csv');
 ```
 
-### **Building from Source**
-```bash
-# Clone repository
-git clone https://github.com/Linol-Hamelton/jtcsv.git
-cd jtcsv
-
-# Install dependencies
-npm install
+### TypeScript Usage
+```typescript
+import { jsonToCsv, csvToJson } from 'jtcsv';
 
-# Run TUI for development
-npm run tui
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
 
-# Test CLI
-npm run cli help
+const users: User[] = [...];
+const csv = jsonToCsv(users);
+const parsed = csvToJson<User>(csv);
 ```
 
-## 🤝 **Contributing**
+## 🤝 Contributing
 
 1. Fork the repository
 2. Create a feature branch
@@ -347,47 +380,57 @@ npm run cli help
 4. Ensure all tests pass: `npm test`
 5. Submit 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
 
 MIT © Ruslan Fomenko
 
-## 🔗 **Links**
+## 🔗 Links
 
 - **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
 
 ---
 
-## 🏆 **Why jtcsv Stands Out**
+## 🎯 When to Use jtcsv
+
+### ✅ **Perfect For:**
+- Simple JSON↔CSV conversion needs
+- Security-conscious applications
+- Large file processing (via streaming)
+- Embedding in other packages (zero deps)
+- TypeScript projects
+- Enterprise applications requiring RFC compliance
+
+### ⚠️ **Consider Alternatives For:**
+- Browser-only applications (use PapaParse)
+- Extremely complex CSV formats
+- Real-time streaming in browsers
 
-### **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
+## 📊 Comparison with Alternatives
+
+| Feature | jtcsv | json2csv | PapaParse | csv-parser |
+|---------|-------|----------|-----------|------------|
+| **Size** | 8KB | 45KB | 35KB | 1.5KB |
+| **Dependencies** | 0 | 4 | 0 | 0 |
+| **JSON→CSV** | ✅ | ✅ | ✅ | ❌ |
+| **CSV→JSON** | ✅ | ✅ | ✅ | ✅ |
+| **Streaming** | ✅ | ❌ | ✅ | ✅ |
+| **Auto-detect Delimiter** | ✅ | ❌ | ✅ | ❌ |
+| **CSV Injection Protection** | ✅ | ❌ | ⚠️ | ❌ |
+| **TypeScript** | ✅ | ✅ | ✅ | ❌ |
+| **RFC 4180** | ✅ | ✅ | ✅ | ✅ |
 
-### **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
+## 🆕 What's New in v1.0.0
 
-### **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
+- **Complete bidirectional conversion** (JSON↔CSV)
+- **Streaming API** for large files (>100MB)
+- **Enhanced security** with CSV injection protection
+- **TypeScript definitions** for all functions
+- **100% test coverage** (108 passing tests)
+- **CI/CD pipeline** with GitHub Actions
+- **Comprehensive documentation**
 
 ---
 
-**Ready for production with enterprise-grade features and unmatched flexibility.**
+**Ready for production use with enterprise-grade security and performance.**"

package/bin/jtcsv.js

@@ -68,8 +68,8 @@ ${color('OPTIONS:', 'bright')}
   ${color('--parse-numbers', 'cyan')}      Parse numeric values in CSV
   ${color('--parse-booleans', 'cyan')}     Parse boolean values in CSV
   ${color('--no-injection-protection', 'cyan')}  Disable CSV injection protection
-  ${color('--max-records=', 'cyan')}N      Maximum records to process (default: 1000000)
-  ${color('--max-rows=', 'cyan')}N         Maximum rows to process (default: 1000000)
+  ${color('--max-records=', 'cyan')}N      Maximum records to process (optional, no limit by default)
+  ${color('--max-rows=', 'cyan')}N         Maximum rows to process (optional, no limit by default)
   ${color('--pretty', 'cyan')}             Pretty print JSON output
   ${color('--silent', 'cyan')}             Suppress all output except errors
   ${color('--verbose', 'cyan')}            Show detailed progress information
@@ -239,8 +239,8 @@ function parseOptions(args) {
     parseNumbers: false,
     parseBooleans: false,
     preventCsvInjection: true,
-    maxRecords: 1000000,
-    maxRows: 1000000,
+    maxRecords: undefined,
+    maxRows: undefined,
     pretty: false,
     silent: false,
     verbose: false

package/csv-to-json.js

@@ -41,8 +41,18 @@ function validateCsvInput(csv, options) {
     throw new ConfigurationError('Delimiter must be a single character');
   }
   
+  // Validate autoDetect
+  if (options?.autoDetect !== undefined && typeof options.autoDetect !== 'boolean') {
+    throw new ConfigurationError('autoDetect must be a boolean');
+  }
+  
+  // Validate candidates
+  if (options?.candidates && !Array.isArray(options.candidates)) {
+    throw new ConfigurationError('candidates must be an array');
+  }
+  
   // Validate maxRows
-  if (options?.maxRows && (typeof options.maxRows !== 'number' || options.maxRows <= 0)) {
+  if (options?.maxRows !== undefined && (typeof options.maxRows !== 'number' || options.maxRows <= 0)) {
     throw new ConfigurationError('maxRows must be a positive number');
   }
   
@@ -50,7 +60,7 @@ function validateCsvInput(csv, options) {
 }
 
 /**
- * Parses a single CSV line with proper escaping
+но * Parses a single CSV line with proper escaping
  * @private
  */
 function parseCsvLine(line, lineNumber, delimiter) {
@@ -69,7 +79,17 @@ function parseCsvLine(line, lineNumber, delimiter) {
     }
 
     if (char === '\\') {
-      escapeNext = true;
+      if (i + 1 === line.length) {
+        // Backslash at end of line - treat as literal
+        currentField += char;
+      } else if (line[i + 1] === '\\') {
+        // Double backslash - add one backslash to field and skip next
+        currentField += char;
+        i++; // Skip next backslash
+      } else {
+        // Escape next character
+        escapeNext = true;
+      }
       continue;
     }
 
@@ -87,6 +107,22 @@ function parseCsvLine(line, lineNumber, delimiter) {
             // Escaped quote inside quotes ("" -> ")
             currentField += '"';
             i++; // Skip next quote
+            // Check if this is the end of the quoted field
+            // Look ahead to see if next char is delimiter or end of line
+            let isEndOfField = false;
+            let j = i + 1;
+            // Skip whitespace
+            while (j < line.length && (line[j] === ' ' || line[j] === '\t')) {
+              j++;
+            }
+            if (j === line.length || line[j] === delimiter) {
+              isEndOfField = true;
+            }
+            
+            if (isEndOfField) {
+              // This is the closing quote
+              insideQuotes = false;
+            }
           }
         } else {
           // Check if this is really the end of the quoted field
@@ -126,6 +162,13 @@ function parseCsvLine(line, lineNumber, delimiter) {
     currentField += char;
   }
 
+  // Handle case where escapeNext is still true at end of line
+  if (escapeNext) {
+    // This happens when line ends with backslash
+    // Add the backslash as literal character
+    currentField += '\\';
+  }
+
   // Add last field
   fields.push(currentField);
 
@@ -171,11 +214,11 @@ function parseCsvValue(value, options) {
   // Parse booleans
   if (parseBooleans) {
     const lowerValue = result.toLowerCase();
-    if (lowerValue === 'true') {
-      return true; 
+    if (lowerValue === 'true') {
+      return true; 
     }
-    if (lowerValue === 'false') {
-      return false; 
+    if (lowerValue === 'false') {
+      return false; 
     }
   }
   
@@ -187,18 +230,66 @@ function parseCsvValue(value, options) {
   return result;
 }
 
+/**
+ * Auto-detect CSV delimiter from content
+ * @private
+ */
+function autoDetectDelimiter(csv, candidates = [';', ',', '\t', '|']) {
+  if (!csv || typeof csv !== 'string') {
+    return ';'; // default
+  }
+
+  const lines = csv.split('\n').filter(line => line.trim().length > 0);
+  
+  if (lines.length === 0) {
+    return ';'; // default
+  }
+
+  // Use first non-empty line for detection
+  const firstLine = lines[0];
+  
+  const counts = {};
+  candidates.forEach(delim => {
+    // Escape special regex characters
+    const escapedDelim = delim.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const regex = new RegExp(escapedDelim, 'g');
+    const matches = firstLine.match(regex);
+    counts[delim] = matches ? matches.length : 0;
+  });
+
+  // Find delimiter with maximum count
+  let maxCount = -1;
+  let detectedDelimiter = ';'; // default
+  
+  for (const [delim, count] of Object.entries(counts)) {
+    if (count > maxCount) {
+      maxCount = count;
+      detectedDelimiter = delim;
+    }
+  }
+
+  // If no delimiter found or tie, return default
+  if (maxCount === 0) {
+    return ';'; // default
+  }
+
+  return detectedDelimiter;
+}
+
 /**
  * Converts CSV string to JSON array
  * 
- * @param {string} csv - CSV string to convert
+  * @param {string} csv - CSV string to convert
  * @param {Object} [options] - Configuration options
- * @param {string} [options.delimiter=';'] - CSV delimiter character
+ * @param {string} [options.delimiter] - CSV delimiter character (default: auto-detected)
+ * @param {boolean} [options.autoDetect=true] - Auto-detect delimiter if not specified
+ * @param {Array} [options.candidates=[';', ',', '\t', '|']] - Candidate delimiters for auto-detection
  * @param {boolean} [options.hasHeaders=true] - Whether CSV has headers row
  * @param {Object} [options.renameMap={}] - Map for renaming column headers (newKey: oldKey)
  * @param {boolean} [options.trim=true] - Trim whitespace from values
  * @param {boolean} [options.parseNumbers=false] - Parse numeric values
  * @param {boolean} [options.parseBooleans=false] - Parse boolean values
- * @param {number} [options.maxRows=1000000] - Maximum number of rows to process
+ * @param {number} [options.maxRows] - Maximum number of rows to process (optional, no limit by default)
  * @returns {Array<Object>} JSON array
  * 
  * @example
@@ -218,15 +309,24 @@ function csvToJson(csv, options = {}) {
     const opts = options && typeof options === 'object' ? options : {};
     
     const {
-      delimiter = ';',
+      delimiter,
+      autoDetect = true,
+      candidates = [';', ',', '\t', '|'],
       hasHeaders = true,
       renameMap = {},
       trim = true,
       parseNumbers = false,
       parseBooleans = false,
-      maxRows = 1000000
+      maxRows
     } = opts;
 
+    // Determine delimiter
+    let finalDelimiter = delimiter;
+    if (!finalDelimiter && autoDetect) {
+      finalDelimiter = autoDetectDelimiter(csv, candidates);
+    }
+    finalDelimiter = finalDelimiter || ';'; // fallback
+
     // Handle empty CSV
     if (csv.trim() === '') {
       return [];
@@ -274,16 +374,28 @@ function csvToJson(csv, options = {}) {
     }
     
     // Check for unclosed quotes
-    if (insideQuotes) {
-      throw new ParsingError('Unclosed quotes in CSV', lines.length);
-    }
+    // Note: This check is moved to parseCsvLine which has better context
+    // for handling escaped quotes like ""
+    // if (insideQuotes) {
+    //   throw new ParsingError('Unclosed quotes in CSV', lines.length);
+    // }
     
     if (lines.length === 0) {
       return [];
     }
 
-    // Limit rows to prevent OOM
-    if (lines.length > maxRows) {
+    // Show warning for large datasets (optional limit)
+    if (lines.length > 1000000 && !maxRows && process.env.NODE_ENV !== 'test') {
+      console.warn(
+        '⚠️ Warning: Processing >1M records in memory may be slow.\n' +
+        '💡 Consider using createCsvToJsonStream() for better performance with large files.\n' +
+        '📊 Current size: ' + lines.length.toLocaleString() + ' rows\n' +
+        '🔧 Tip: Use { maxRows: N } option to set a custom limit if needed.'
+      );
+    }
+
+    // Apply optional row limit if specified
+    if (maxRows && lines.length > maxRows) {
       throw new LimitError(
         `CSV size exceeds maximum limit of ${maxRows} rows`,
         maxRows,
@@ -297,7 +409,7 @@ function csvToJson(csv, options = {}) {
     // Parse headers if present
     if (hasHeaders && lines.length > 0) {
       try {
-        headers = parseCsvLine(lines[0], 1, delimiter).map(header => {
+        headers = parseCsvLine(lines[0], 1, finalDelimiter).map(header => {
           const trimmed = trim ? header.trim() : header;
           // Apply rename map
           return renameMap[trimmed] || trimmed;
@@ -312,7 +424,7 @@ function csvToJson(csv, options = {}) {
     } else {
       // Generate numeric headers from first line
       try {
-        const firstLineFields = parseCsvLine(lines[0], 1, delimiter);
+        const firstLineFields = parseCsvLine(lines[0], 1, finalDelimiter);
         headers = firstLineFields.map((_, index) => `column${index + 1}`);
       } catch (error) {
         if (error instanceof ParsingError) {
@@ -334,7 +446,7 @@ function csvToJson(csv, options = {}) {
       }
       
       try {
-        const fields = parseCsvLine(line, i + 1, delimiter);
+        const fields = parseCsvLine(line, i + 1, finalDelimiter);
         
         // Handle mismatched field count
         const row = {};
@@ -399,7 +511,7 @@ function validateCsvFilePath(filePath) {
  * @returns {Promise<Array<Object>>} Promise that resolves to JSON array
  * 
  * @example
- * const { readCsvAsJson } = require('./csv-to-json');
+ *     const { readCsvAsJson } = require('./csv-to-json');
  * 
  * const json = await readCsvAsJson('./data.csv', {
  *   delimiter: ',',
@@ -483,7 +595,8 @@ function readCsvAsJsonSync(filePath, options = {}) {
 module.exports = {
   csvToJson,
   readCsvAsJson,
-  readCsvAsJsonSync
+  readCsvAsJsonSync,
+  autoDetectDelimiter
 };
 
 // For ES6 module compatibility

package/index.d.ts

@@ -11,7 +11,7 @@ declare module 'jtcsv' {
     renameMap?: Record<string, string>;
     /** Template for guaranteed column order */
     template?: Record<string, any>;
-    /** Maximum number of records to process (default: 1,000,000) */
+    /** Maximum number of records to process (optional, no limit by default) */
     maxRecords?: number;
     /** Prevent CSV injection attacks by escaping formulas (default: true) */
     preventCsvInjection?: boolean;
@@ -26,8 +26,12 @@ declare module 'jtcsv' {
 
   // CSV to JSON interfaces
   export interface CsvToJsonOptions {
-    /** CSV delimiter (default: ';') */
+    /** CSV delimiter (default: auto-detected) */
     delimiter?: string;
+    /** Auto-detect delimiter if not specified (default: true) */
+    autoDetect?: boolean;
+    /** Candidate delimiters for auto-detection (default: [';', ',', '\t', '|']) */
+    candidates?: string[];
     /** Whether CSV has headers row (default: true) */
     hasHeaders?: boolean;
     /** Map for renaming column headers { newKey: oldKey } */
@@ -38,7 +42,7 @@ declare module 'jtcsv' {
     parseNumbers?: boolean;
     /** Parse boolean values (default: false) */
     parseBooleans?: boolean;
-    /** Maximum number of rows to process (default: 1,000,000) */
+    /** Maximum number of rows to process (optional, no limit by default) */
     maxRows?: number;
   }
 
@@ -210,6 +214,17 @@ declare module 'jtcsv' {
     options?: CsvToJsonOptions
   ): Record<string, any>[];
 
+  /**
+   * Auto-detect CSV delimiter from content
+   * @param csv CSV content string
+   * @param candidates Candidate delimiters to test (default: [';', ',', '\t', '|'])
+   * @returns Detected delimiter
+   */
+  export function autoDetectDelimiter(
+    csv: string,
+    candidates?: string[]
+  ): string;
+
   /**
    * Save data as JSON file with security validation
    * @param data Data to save as JSON

package/index.js

@@ -21,6 +21,7 @@ module.exports = {
   csvToJson: csvToJsonModule.csvToJson,
   readCsvAsJson: csvToJsonModule.readCsvAsJson,
   readCsvAsJsonSync: csvToJsonModule.readCsvAsJsonSync,
+  autoDetectDelimiter: csvToJsonModule.autoDetectDelimiter,
 
   // JSON save functions
   saveAsJson: jsonSaveModule.saveAsJson,

package/json-to-csv.js

@@ -73,8 +73,8 @@ function validateInput(data, options) {
  * @param {string} [options.delimiter=';'] - CSV delimiter character
  * @param {boolean} [options.includeHeaders=true] - Whether to include headers row
  * @param {Object} [options.renameMap={}] - Map for renaming column headers (oldKey: newKey)
- * @param {Object} [options.template={}] - Template object to ensure consistent column order
- * @param {number} [options.maxRecords=1000000] - Maximum number of records to process
+* @param {Object} [options.template={}] - Template object to ensure consistent column order
+ * @param {number} [options.maxRecords] - Maximum number of records to process (optional, no limit by default)
  * @param {boolean} [options.preventCsvInjection=true] - Prevent CSV injection attacks by escaping formulas
  * @param {boolean} [options.rfc4180Compliant=true] - Ensure RFC 4180 compliance (proper quoting, line endings)
  * @returns {string} CSV formatted string
@@ -106,7 +106,7 @@ function jsonToCsv(data, options = {}) {
       includeHeaders = true,
       renameMap = {},
       template = {},
-      maxRecords = 1000000,
+      maxRecords,
       preventCsvInjection = true,
       rfc4180Compliant = true
     } = opts;
@@ -116,8 +116,18 @@ function jsonToCsv(data, options = {}) {
       return '';
     }
 
-    // Limit data size to prevent OOM
-    if (data.length > maxRecords) {
+    // Show warning for large datasets (optional limit)
+    if (data.length > 1000000 && !maxRecords && process.env.NODE_ENV !== 'test') {
+      console.warn(
+        '⚠️ Warning: Processing >1M records in memory may be slow.\n' +
+        '💡 Consider processing data in batches or using streaming for large files.\n' +
+        '📊 Current size: ' + data.length.toLocaleString() + ' records\n' +
+        '🔧 Tip: Use { maxRecords: N } option to set a custom limit if needed.'
+      );
+    }
+
+    // Apply optional record limit if specified
+    if (maxRecords && data.length > maxRecords) {
       throw new LimitError(
         `Data size exceeds maximum limit of ${maxRecords} records`,
         maxRecords,
@@ -372,7 +382,7 @@ function validateFilePath(filePath) {
  * @returns {Promise<void>}
  * 
  * @example
- * const { saveAsCsv } = require('./json-to-csv');
+ *     const { saveAsCsv } = require('./json-to-csv');
  * 
  * await saveAsCsv(data, './output.csv', {
  *   delimiter: ',',

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "jtcsv",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Complete JSON↔CSV converter for Node.js with streaming, security, TUI, and TypeScript support - Zero dependencies",
   "main": "index.js",
   "types": "index.d.ts",
   "bin": {
-    "jtcsv": "./bin/jtcsv.js"
+    "jtcsv": "bin/jtcsv.js"
   },
   "scripts": {
     "test": "jest",
@@ -54,7 +54,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Linol-Hamelton/jtcsv.git"
+    "url": "git+https://github.com/Linol-Hamelton/jtcsv.git"
   },
   "bugs": {
     "url": "https://github.com/Linol-Hamelton/jtcsv/issues"
@@ -76,12 +76,12 @@
     "cli-tui.js"
   ],
   "devDependencies": {
-    "jest": "^29.0.0",
-    "eslint": "^8.0.0"
+    "eslint": "8.57.1",
+    "jest": "^29.0.0"
   },
   "optionalDependencies": {
     "blessed": "^0.1.81",
     "blessed-contrib": "^4.11.0"
-  }
+  },
+  "type": "commonjs"
 }
-