jtcsv 2.1.3 → 2.1.5

package/README.md

@@ -1,172 +1,48 @@
-# jtcsv - Complete JSON ↔ CSV Converter
+# jtcsv - JSON <-> CSV toolkit for Node.js and browser
 
-**Version 2.0** - Now with full browser support, Web Workers, and streaming!
-
-[![npm version](https://img.shields.io/npm/v/jtcsvps://www.npmjs.com/package/jtcsv)jtcsv
+[![npm version](https://img.shields.io/npm/v/jtcsv)](https://www.npmjs.com/package/jtcsv)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Zero-Deps Core](https://img.shields.io/badge/core-zero%20deps-brightgreen.svg)](https://www.npmjs.com/package/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.
-Zero-deps core with optional add-ons (TUI, Excel) for advanced workflows.
-
-## ✨ Features
-
-### 🚀 Core Features
-- **Bidirectional Conversion**: JSON ↔ CSV with full type preservation
-- **Zero-Deps Core**: Pure JavaScript/TypeScript core with optional add-ons
-- **TypeScript Support**: Full type definitions included
-- **Security First**: Built-in CSV injection protection
-- **RFC 4180 Compliant**: Proper CSV formatting and escaping
-
-### 🌐 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
+[![Zero-Deps Core](https://img.shields.io/badge/core-zero%20deps-brightgreen.svg)](https://www.npmjs.com/package/jtcsv)
 
-### ⚡ 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
+Fast JSON <-> CSV conversion with streaming helpers, NDJSON/TSV support, and optional integrations.
 
-### 🔧 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
+## Features
+- JSON <-> CSV conversion with security defaults
+- Streaming helpers and async iterator API
+- NDJSON and TSV helpers
+- Browser bundle with Web Worker helpers
+- Optional plugin system and framework adapters
+- CLI and optional TUI
 
-### 🔌 Framework Integrations (Optional)
-- **NestJS**: `@jtcsv/nestjs`
-- **Remix**: `@jtcsv/remix`
-- **Nuxt**: `@jtcsv/nuxt`
-- **SvelteKit**: `@jtcsv/sveltekit`
-- **Hono**: `@jtcsv/hono`
-- **tRPC**: `@jtcsv/trpc`
-
-## 📦 Installation
-
-### Node.js
+## Installation
 ```bash
 npm install jtcsv
 ```
 
 ### Optional add-ons
 ```bash
-# Terminal UI
 npm install @jtcsv/tui
-
-# Excel plugin
 npm install @jtcsv/excel exceljs
+npm install @jtcsv/validator
 ```
 
-### Browser (CDN)
-```html
-<!-- UMD version (global jtcsv variable) -->
-<script src="https://cdn.jsdelivr.net/npm/jtcsvst/jtcsv.umd.js"></script>
-
-<!-- ESM version -->
-<script type="module">
-  import { jsonToCsv } from 'https://cdn.jsdelivr.net/npm/jtcsvst/jtcsv.esm.js';
-</script>
-```
-
-## 🚀 Quick Start
-
-### Node.js Usage
+## Quick start (Node.js)
 ```javascript
-const { jsonToCsv, csvToJson } = 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' }
 ];
 
-const csv = jsonToCsv(data, {
-  delimiter: ',',
-  includeHeaders: true,
-  preventCsvInjection: true
-});
+const csv = jsonToCsv(data, { delimiter: ',', includeHeaders: true });
+const json = csvToJson(csv, { delimiter: ',', parseNumbers: true });
 
 console.log(csv);
-// id,name,email
-// 1,John,john@example.com
-// 2,Jane,jane@example.com
-
-// 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
-});
-
 console.log(json);
-// [
-//   { id: 1, name: 'John', email: 'john@example.com' },
-//   { id: 2, name: 'Jane', email: 'jane@example.com' }
-// ]
-```
-
-### Browser Usage
-```javascript
-// Using global variable (UMD)
-const csv = window.jtcsv.jsonToCsv(data, { delimiter: ',' });
-
-// Download as file
-window.jtcsv.downloadAsCsv(data, 'export.csv', { delimiter: ',' });
-
-// Parse uploaded file
-const fileInput = document.querySelector('input[type="file"]');
-const json = await window.jtcsv.parseCsvFile(fileInput.files[0], {
-  delimiter: ',',
-  parseNumbers: true
-});
-
-// 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)}%`);
-});
 ```
 
-## 🔧 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:**
-Fast path parsing is the default pipeline; use `fastPathMode` to control row shape.
-- `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
-- `useFastPath` (boolean, default: true): Enable fast-path parser (set `false` to force quote-aware path)
-- `fastPathMode` (string, default: 'objects'): `'objects'` for object rows, `'compact'` for arrays (lower memory), `'stream'` to return an async iterator
-
-#### `csvToJsonIterator(csv, options)`
-Convert CSV to JSON rows as an async iterator for large inputs.
-You can also call `csvToJson(csv, { fastPathMode: 'stream' })` to get the same async iterator.
-
-**Example:**
+### Async iterator
 ```javascript
 const { csvToJsonIterator } = require('jtcsv');
 
@@ -176,222 +52,65 @@ for await (const row of csvToJsonIterator(csv, { fastPathMode: 'compact' })) {
 }
 ```
 
-### Browser-Specific Functions
+## Browser usage
+- Bundler: `import { csvToJson, jsonToCsv } from 'jtcsv/browser';`
+- CDN UMD: `https://cdn.jsdelivr.net/npm/jtcsv/dist/jtcsv.umd.js`
+- CDN ESM: `https://cdn.jsdelivr.net/npm/jtcsv/dist/jtcsv.esm.js`
 
-#### `downloadAsCsv(data, filename, options)`
-Converts and downloads JSON as CSV file.
+See `README-browser.md` for full browser API and worker helpers.
 
-#### `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.
+## CLI
+```bash
+npx jtcsv csv-to-json input.csv output.json
+npx jtcsv json-to-csv input.json output.csv
+npx jtcsv stream csv-to-json big.csv output.json
+npx jtcsv batch json-to-csv "data/*.json" output/
 
-**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
+# optional TUI
+npx jtcsv tui
+```
 
-#### `parseCSVWithWorker(csvInput, options, onProgress)`
-Parses CSV using Web Workers with progress tracking.
+See `CLI.md` for full command list and options.
 
-## 💡 Examples
+## Demos
+Run these from the repo root:
+```bash
+# Express API demo
+npm run demo
 
-### React Component Example
-```jsx
-import React, { useState } from 'react';
-import { parseCsvFile, downloadAsCsv } from 'jtcsv
+# Web demo (Vite dev server on http://localhost:3000)
+npm run demo:web
 
-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);
-    }
-  };
-  
-  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>
-  );
-}
+# Preview built demo
+npm run demo:serve
 ```
 
-### Large File Processing with Progress
-```javascript
-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;
-  }
-}
+From inside `demo/` use:
+```bash
+npm run dev
+npm run preview
+npm run serve
 ```
 
-### Security: CSV Injection Protection
-```javascript
-const dangerousData = [
-  { formula: '=SUM(1,2)', command: '=cmd|"/c calc"!A1' }
-];
+## Plugin system
+The plugin-enabled API is exported from `jtcsv/plugins`.
 
-// 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
+```javascript
+const { create } = require('jtcsv/plugins');
 
-// Without protection
-const unsafeCsv = jsonToCsv(dangerousData, { preventCsvInjection: false });
-// formula,command
-// =SUM(1,2),=cmd|"/c calc"!A1
-// WARNING: This could execute commands in Excel!
+const jtcsv = create();
+jtcsv.use('my-plugin', { name: 'My Plugin', version: '1.0.0' });
 ```
 
-## 📊 Performance
-
-### Benchmark Results (Node.js 22, 10K rows/records)
-
-**CSV → JSON (10K rows)**
+See `README-PLUGINS.md` and `plugins/README.md` for integrations.
 
-| Library | Time | Memory | Rank |
-|---------|------|--------|------|
-| **JTCSV (FastPath Compact)** | 16.79 ms | 4.47 MB | 🥇 1st |
-| **JTCSV (FastPath Stream)** | 18.27 ms | 6.03 MB | 🥈 2nd |
-| **JTCSV** | 19.76 ms | 8.96 MB | 🥉 3rd |
-| PapaParse | 21.57 ms | 6.97 MB | 4th |
-| csv-parser | 30.52 ms | 6.53 MB | 5th |
-
-**JSON → CSV (10K records)**
-
-| Library | Time | Memory | Rank |
-|---------|------|--------|------|
-| **JTCSV** | 11.21 ms | 4.77 MB | 🥇 1st |
-| json2csv | 12.27 ms | 12.11 MB | 🥈 2nd |
-
-### Scaling (JTCSV only)
-
-| Rows/Records | CSV→JSON Time (FastPath Compact) | JSON→CSV Time (JTCSV) | CSV→JSON Memory | JSON→CSV Memory |
-|--------------|----------------------------------|-----------------------|-----------------|-----------------|
-| 1,000 | 2.06 ms | 1.04 ms | 2.15 MB | 0.52 MB |
-| 10,000 | 14.68 ms | 8.23 ms | 2.11 MB | 4.14 MB |
-| 100,000 | 164.18 ms | 90.93 ms | 44.93 MB | 34.79 MB |
-
-See `BENCHMARK-RESULTS.md` and `docs/PERFORMANCE.md` for environment details and methodology.
-
-## 🛠️ Development
-
-### Building from Source
+## Development
+Run from the repo root:
 ```bash
-# Clone repository
-git clone https://github.com/Linol-Hamelton/jtcsv.git
-cd jtcsv
-
-# Install dependencies
-npm install
-
-# Build browser version
-npm run build
-
-# 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
+npm run test:coverage
+npm run build
 ```
 
-## 🤝 Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.
-
-1. Fork the repository
-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
-
-## 📄 License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## 🙏 Acknowledgments
-
-- 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
-
-## 📞 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)
-
----
-
-**Happy coding!** If you find this library useful, please consider giving it a star on GitHub ⭐
+## License
+MIT. See `LICENSE`.

package/csv-to-json.js

@@ -114,8 +114,9 @@ function validateCsvInput(csv, options) {
  * Parses a value based on options
  * @private
  */
-function parseCsvValue(value, options) {
-  const { trim = true, parseNumbers = false, parseBooleans = false } = options;
+function parseCsvValue(value, options) {
+  /* istanbul ignore next */
+  const { trim = true, parseNumbers = false, parseBooleans = false } = options;
   
   let result = value;
   
@@ -131,10 +132,11 @@ function parseCsvValue(value, options) {
   // Parse numbers
   if (parseNumbers && /^-?\d+(\.\d+)?$/.test(result)) {
     const num = parseFloat(result);
-    if (!isNaN(num)) {
-      return num;
-    }
-  }
+    /* istanbul ignore next */
+    if (!isNaN(num)) {
+      return num;
+    }
+  }
   
   // Parse booleans
   if (parseBooleans) {
@@ -342,12 +344,13 @@ function csvToJson(csv, options = {}) {
           console.warn(`[jtcsv] Line ${totalRows}: ${fields.length - headers.length} extra fields ignored`);
         }
       });
-    } catch (error) {
-      if (error && error.code === 'FAST_PATH_UNCLOSED_QUOTES') {
-        throw new ParsingError(error.message, error.lineNumber);
-      }
-      throw error;
-    }
+    } catch (error) {
+      if (error && error.code === 'FAST_PATH_UNCLOSED_QUOTES') {
+        const lineInfo = error.lineNumber ? ` at line ${error.lineNumber}` : '';
+        throw new ParsingError(`Unclosed quotes in CSV${lineInfo}`, error.lineNumber);
+      }
+      throw error;
+    }
 
     if (!headers) {
       return [];
@@ -371,7 +374,8 @@ function csvToJson(csv, options = {}) {
   }, 'PARSE_FAILED', { function: 'csvToJson' });
 }
 
-async function* csvToJsonIterator(csv, options = {}) {
+/* istanbul ignore next */
+async function* csvToJsonIterator(csv, options = {}) {
   validateCsvInput(csv, options);
 
   const opts = options && typeof options === 'object' ? options : {};
@@ -498,7 +502,8 @@ async function* csvToJsonIterator(csv, options = {}) {
     }
   } catch (error) {
     if (error && error.code === 'FAST_PATH_UNCLOSED_QUOTES') {
-      throw new ParsingError(error.message, error.lineNumber);
+      const lineInfo = error.lineNumber ? ` at line ${error.lineNumber}` : '';
+      throw new ParsingError(`Unclosed quotes in CSV${lineInfo}`, error.lineNumber);
     }
     throw error;
   }
@@ -638,24 +643,27 @@ function createTransformHooks() {
  * @param {number} maxSize - Maximum cache size (default: 100)
  * @returns {DelimiterCache} New DelimiterCache instance
  */
-function createDelimiterCache(maxSize = 100) {
-  return new DelimiterCache(maxSize);
-}
+/* istanbul ignore next */
+function createDelimiterCache(maxSize = 100) {
+  return new DelimiterCache(maxSize);
+}
 
 /**
  * Gets statistics from the global delimiter cache
  * @returns {Object} Cache statistics
  */
-function getDelimiterCacheStats() {
-  return globalDelimiterCache.getStats();
-}
+/* istanbul ignore next */
+function getDelimiterCacheStats() {
+  return globalDelimiterCache.getStats();
+}
 
 /**
  * Clears the global delimiter cache
  */
-function clearDelimiterCache() {
-  globalDelimiterCache.clear();
-}
+/* istanbul ignore next */
+function clearDelimiterCache() {
+  globalDelimiterCache.clear();
+}
 
 // Export the functions
 module.exports = {
@@ -674,6 +682,7 @@ module.exports = {
 };
 
 // For ES6 module compatibility
-if (typeof module !== 'undefined' && module.exports) {
-  module.exports.default = csvToJson;
-}
+/* istanbul ignore next */
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports.default = csvToJson;
+}