jtcsv 2.2.7 → 3.0.0

package/examples/simple-usage.ts

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+
+/**
+ * Простой пример использования новых возможностей JTCSV 2.1.0
+ * Демонстрация Fast-Path Engine, NDJSON и Plugin System
+ * 
+ * @version 1.0.0
+ * @date 2026-01-22
+ */
+
+// Используем require для совместимости с текущей структурой проекта
+const { jsonToCsv, csvToJson } = require('../index.js');
+import type { JsonToCsvOptions, CsvToJsonOptions } from '../src/types';
+
+(async () => {
+  console.log('🚀 JTCSV 2.1.0 - Демонстрация новых возможностей\n');
+
+  // ============================================================================
+  // 1. Базовое использование (обратная совместимость)
+  // ============================================================================
+
+  console.log('1. 📦 Базовое использование (обратная совместимость)');
+  console.log('='.repeat(60));
+
+  const sampleData = [
+    { id: 1, name: 'John Doe', age: 30, city: 'New York' },
+    { id: 2, name: 'Jane Smith', age: 25, city: 'London' },
+    { id: 3, name: 'Bob Johnson', age: 35, city: 'Tokyo' }
+  ];
+
+  // Конвертация JSON → CSV
+  const csv = jsonToCsv(sampleData, { delimiter: ',' });
+  console.log('📄 CSV результат:');
+  console.log(csv);
+  console.log();
+
+  // Конвертация CSV → JSON
+  const json = csvToJson(csv, { delimiter: ',' });
+  console.log('📊 JSON результат:');
+  console.log(JSON.stringify(json, null, 2));
+  console.log();
+
+  // ============================================================================
+  // 2. Fast-Path Engine (оптимизированный парсинг)
+  // ============================================================================
+
+  console.log('\n2. ⚡ Fast-Path Engine (оптимизированный парсинг)');
+  console.log('='.repeat(60));
+
+  const FastPathEngine = require('../src/engines/fast-path-engine');
+  const engine = new FastPathEngine();
+
+  const largeCsv = `id,name,age,city
+1,John Doe,30,New York
+2,Jane Smith,25,London
+3,Bob Johnson,35,Tokyo
+4,Alice Brown,28,Paris
+5,Charlie Wilson,42,Berlin`;
+
+  console.log('📊 Парсинг CSV с Fast-Path Engine:');
+  const fastPathResult = engine.parse(largeCsv, { delimiter: ',' });
+  console.log(JSON.stringify(fastPathResult, null, 2));
+  console.log();
+
+  // ============================================================================
+  // 3. NDJSON поддержка (Newline Delimited JSON)
+  // ============================================================================
+
+  console.log('\n3. 📝 NDJSON поддержка (Newline Delimited JSON)');
+  console.log('='.repeat(60));
+
+  const { jsonToNdjson, ndjsonToJson } = require('jtcsv');
+
+  const ndjsonData = [
+    { id: 1, name: 'John', active: true },
+    { id: 2, name: 'Jane', active: false },
+    { id: 3, name: 'Bob', active: true }
+  ];
+
+  // Конвертация в NDJSON
+  const ndjson = jsonToNdjson(ndjsonData);
+  console.log('📄 NDJSON результат:');
+  console.log(ndjson);
+  console.log();
+
+  // Обратная конвертация
+  const fromNdjson = ndjsonToJson(ndjson);
+  console.log('📊 JSON из NDJSON:');
+  console.log(JSON.stringify(fromNdjson, null, 2));
+  console.log();
+
+  // ============================================================================
+  // 4. Потоковая обработка
+  // ============================================================================
+
+  console.log('\n4. 🌊 Потоковая обработка');
+  console.log('='.repeat(60));
+
+  const { streamCsvToJson, streamJsonToCsv } = require('jtcsv');
+
+  console.log('📊 Пример потоковой обработки CSV:');
+  
+  // Создание потока CSV данных
+  const csvStream = `id,name,age
+1,John,30
+2,Jane,25
+3,Bob,35`;
+
+  const jsonStream = streamCsvToJson(csvStream, { delimiter: ',' });
+  
+  // В реальном приложении здесь была бы обработка потока
+  console.log('✅ Поток создан успешно');
+  console.log();
+
+  // ============================================================================
+  // 5. Асинхронные функции
+  // ============================================================================
+
+  console.log('\n5. ⏱️ Асинхронные функции');
+  console.log('='.repeat(60));
+
+  try {
+    // Использование асинхронных версий функций
+    const asyncCsv = await jsonToCsv(sampleData, { delimiter: ';' });
+    console.log('📄 Асинхронный CSV результат:');
+    console.log(asyncCsv.substring(0, 100) + '...');
+    console.log();
+  } catch (error: any) {
+    console.error('❌ Ошибка при асинхронной конвертации:', error.message);
+  }
+
+  // ============================================================================
+  // 6. Многопоточная обработка
+  // ============================================================================
+
+  console.log('\n6. 🚀 Многопоточная обработка');
+  console.log('='.repeat(60));
+
+  try {
+    const { processCsvMultithreaded } = require('../src/workers/csv-multithreaded');
+    
+    console.log('📊 Запуск многопоточной обработки...');
+    
+    // В реальном приложении здесь была бы обработка больших данных
+    console.log('✅ Многопоточная система готова к использованию');
+    console.log();
+  } catch (error) {
+    console.log('ℹ️ Многопоточная обработка доступна только в Node.js');
+    console.log();
+  }
+
+  // ============================================================================
+  // 7. TypeScript типы
+  // ============================================================================
+
+  console.log('\n7. 📘 TypeScript типы');
+  console.log('='.repeat(60));
+
+  // Демонстрация TypeScript типов
+  const typedOptions: JsonToCsvOptions = {
+    delimiter: ',',
+    includeHeaders: true,
+    maxRecords: 100,
+    preventCsvInjection: true,
+    rfc4180Compliant: true
+  };
+
+  console.log('✅ TypeScript типы корректно работают');
+  console.log('📋 Пример опций:', JSON.stringify(typedOptions, null, 2));
+  console.log();
+
+  // ============================================================================
+  // Заключение
+  // ============================================================================
+
+  console.log('\n🎉 Демонстрация завершена!');
+  console.log('='.repeat(60));
+  console.log('\n📚 Основные возможности JTCSV 2.1.0:');
+  console.log('   • ⚡ Fast-Path Engine для оптимизированного парсинга');
+  console.log('   • 📝 Поддержка NDJSON (Newline Delimited JSON)');
+  console.log('   • 🌊 Потоковая обработка больших данных');
+  console.log('   • ⏱️ Асинхронные и многопоточные функции');
+  console.log('   • 📘 Полная поддержка TypeScript');
+  console.log('   • 🔌 Расширяемая плагинная система');
+  console.log('   • 🛡️ Защита от CSV инъекций');
+  console.log('   • 📊 Поддержка различных форматов (CSV, TSV, NDJSON)');
+  console.log('\n🚀 Готово к использованию в production!');
+})();
+
+// Обработка ошибок
+process.on('unhandledRejection', (error) => {
+  console.error('❌ Необработанная ошибка:', error);
+  process.exit(1);
+});

package/examples/streaming-example.js

@@ -364,7 +364,9 @@ async function exampleBidirectionalStreaming() {
     // Cleanup on error
     try {
       await fs.promises.unlink(tempFile);
-    } catch (e) {}
+    } catch (_e) {
+      // Ignore cleanup errors
+    }
   }
 }
 
@@ -413,7 +415,4 @@ module.exports = {
   exampleJsonToCsvStreaming,
   exampleCsvToJsonStreaming,
   exampleBidirectionalStreaming
-};
-
-
-
+};

package/examples/streaming-example.ts

@@ -0,0 +1,419 @@
+#!/usr/bin/env node
+
+/**
+ * Streaming Example for jtcsv
+ * 
+ * Demonstrates bidirectional streaming with large datasets
+ * and real-time progress monitoring.
+ */
+
+import fs from "fs";
+import path from "path";
+const {  pipeline  } = await import("stream/promises");
+import jtcsv from "../index.js";
+
+async function generateLargeJsonFile(filePath, recordCount) {
+  console.log(`Generating ${recordCount} records...`);
+  
+  const writeStream = fs.createWriteStream(filePath, 'utf8');
+  
+  // Write opening bracket for JSON array
+  writeStream.write('[');
+  
+  for (let i = 1; i <= recordCount; i++) {
+    const record = {
+      id: i,
+      name: `User ${i}`,
+      email: `user${i}@example.com`,
+      age: Math.floor(Math.random() * 50) + 18,
+      active: Math.random() > 0.5,
+      score: Math.random() * 100,
+      tags: ['customer', `tier${Math.floor(Math.random() * 3) + 1}`],
+      metadata: {
+        created: new Date().toISOString(),
+        updated: new Date().toISOString(),
+        version: '1.0.0'
+      }
+    };
+    
+    const jsonRecord = JSON.stringify(record);
+    writeStream.write(jsonRecord);
+    
+    if (i < recordCount) {
+      writeStream.write(',');
+    }
+    
+    // Show progress every 10,000 records
+    if (i % 10000 === 0) {
+      process.stdout.write(`  Generated ${i} records\r`);
+    }
+  }
+  
+  // Write closing bracket
+  writeStream.write(']');
+  
+  await new Promise((resolve) => {
+    writeStream.end(() => {
+      console.log(`\nGenerated ${recordCount} records in ${filePath}`);
+      resolve();
+    });
+  });
+}
+
+async function exampleJsonToCsvStreaming() {
+  console.log('\n=== Example 1: JSON to CSV Streaming ===');
+  
+  const inputFile = './examples/large-data.json';
+  const outputFile = './examples/large-data.csv';
+  
+  // Generate test data if needed
+  if (!fs.existsSync(inputFile)) {
+    await generateLargeJsonFile(inputFile, 100000);
+  }
+  
+  console.log('Converting JSON to CSV using streaming...');
+  
+  const startTime = Date.now();
+  
+  try {
+    // Create readable stream from file
+    const readStream = fs.createReadStream(inputFile, 'utf8');
+    
+    // Parse JSON stream (simplified - in real app use proper JSON stream parser)
+    let buffer = '';
+    let recordCount = 0;
+    
+    const streamModule = require("stream");
+    const jsonStream = new streamModule.Transform({
+      objectMode: true,
+      transform(chunk, encoding, callback) {
+        buffer += chunk;
+        
+        // Simple JSON parsing for demonstration
+        // In production, use a proper JSON stream parser
+        try {
+          const data = JSON.parse(buffer);
+          if (Array.isArray(data)) {
+            data.forEach(item => {
+              this.push(item);
+              recordCount++;
+              
+              if (recordCount % 10000 === 0) {
+                console.log(`  Processed ${recordCount} records`);
+              }
+            });
+          }
+          buffer = '';
+        } catch (error) {
+          // Incomplete JSON, wait for more data
+        }
+        
+        callback();
+      },
+      
+      flush(callback) {
+        // Process any remaining data
+        if (buffer.trim()) {
+          try {
+            const data = JSON.parse(buffer);
+            if (Array.isArray(data)) {
+              data.forEach(item => {
+                this.push(item);
+                recordCount++;
+              });
+            }
+          } catch (error) {
+            console.error('Error parsing final JSON:', error.message);
+          }
+        }
+        callback();
+      }
+    });
+    
+    // Create CSV transform stream
+    const csvStream = jtcsv.createJsonToCsvStream({
+      delimiter: ',',
+      includeHeaders: true,
+      renameMap: {
+        id: 'ID',
+        name: 'Full Name',
+        email: 'Email Address',
+        age: 'Age',
+        active: 'Active Status',
+        score: 'Score',
+        'metadata.created': 'Created Date',
+        'metadata.updated': 'Updated Date'
+      },
+      preventCsvInjection: true,
+      rfc4180Compliant: true
+    });
+    
+    // Create write stream
+    const writeStream = fs.createWriteStream(outputFile, 'utf8');
+    
+    // Add UTF-8 BOM for Excel compatibility
+    writeStream.write('\uFEFF');
+    
+    // Pipe streams together
+    await pipeline(
+      readStream,
+      jsonStream,
+      csvStream,
+      writeStream
+    );
+    
+    const elapsed = Date.now() - startTime;
+    console.log(`✓ Converted ${recordCount} records in ${elapsed}ms`);
+    
+    // Show file sizes
+    const inputStats = fs.statSync(inputFile);
+    const outputStats = fs.statSync(outputFile);
+    
+    console.log(`  Input:  ${(inputStats.size / 1024 / 1024).toFixed(2)} MB`);
+    console.log(`  Output: ${(outputStats.size / 1024 / 1024).toFixed(2)} MB`);
+    
+  } catch (error) {
+    console.error('Error:', error.message);
+  }
+}
+
+async function exampleCsvToJsonStreaming() {
+  console.log('\n=== Example 2: CSV to JSON Streaming ===');
+  
+  const inputFile = './examples/large-data.csv';
+  const outputFile = './examples/streamed-output.json';
+  
+  if (!fs.existsSync(inputFile)) {
+    console.log('CSV file not found. Run Example 1 first.');
+    return;
+  }
+  
+  console.log('Converting CSV to JSON using streaming...');
+  
+  const startTime = Date.now();
+  
+  try {
+    // Create CSV read stream
+    const readStream = fs.createReadStream(inputFile, 'utf8');
+    
+    // Create CSV to JSON transform stream
+    const jsonStream = jtcsv.createCsvToJsonStream({
+      delimiter: ',',
+      hasHeaders: true,
+      parseNumbers: true,
+      parseBooleans: true,
+      renameMap: {
+        'ID': 'id',
+        'Full Name': 'name',
+        'Email Address': 'email',
+        'Age': 'age',
+        'Active Status': 'active',
+        'Score': 'score',
+        'Created Date': 'created',
+        'Updated Date': 'updated'
+      }
+    });
+    
+    // Create JSON write stream
+    const writeStream = fs.createWriteStream(outputFile, 'utf8');
+    
+    // Write opening bracket
+    writeStream.write('[');
+    
+    let recordCount = 0;
+    let firstRecord = true;
+    
+    // Custom transform to format JSON array
+    const arrayFormatter = (require("stream").Transform)({
+      objectMode: true,
+      transform(chunk, encoding, callback) {
+        const jsonRecord = JSON.stringify(chunk);
+        
+        if (!firstRecord) {
+          writeStream.write(',');
+        } else {
+          firstRecord = false;
+        }
+        
+        writeStream.write(jsonRecord);
+        
+        recordCount++;
+        if (recordCount % 10000 === 0) {
+          console.log(`  Processed ${recordCount} records`);
+        }
+        
+        callback();
+      },
+      
+      flush(callback) {
+        // Write closing bracket
+        writeStream.write(']');
+        callback();
+      }
+    });
+    
+    // Pipe streams together
+    await pipeline(
+      readStream,
+      jsonStream,
+      arrayFormatter
+    );
+    
+    // Close write stream
+    await new Promise((resolve) => {
+      writeStream.end(() => resolve());
+    });
+    
+    const elapsed = Date.now() - startTime;
+    console.log(`✓ Converted ${recordCount} records in ${elapsed}ms`);
+    
+    // Verify roundtrip
+    const inputStats = fs.statSync(inputFile);
+    const outputStats = fs.statSync(outputFile);
+    
+    console.log(`  Input:  ${(inputStats.size / 1024 / 1024).toFixed(2)} MB`);
+    console.log(`  Output: ${(outputStats.size / 1024 / 1024).toFixed(2)} MB`);
+    
+    // Sample verification
+    const sampleData = require(outputFile).slice(0, 3);
+    console.log('\nSample of converted data (first 3 records):');
+    console.log(JSON.stringify(sampleData, null, 2));
+    
+  } catch (error) {
+    console.error('Error:', error.message);
+  }
+}
+
+async function exampleBidirectionalStreaming() {
+  console.log('\n=== Example 3: Bidirectional Streaming Pipeline ===');
+  
+  const inputFile = './examples/large-data.json';
+  const tempFile = './examples/temp-stream.csv';
+  const outputFile = './examples/final-stream.json';
+  
+  if (!fs.existsSync(inputFile)) {
+    await generateLargeJsonFile(inputFile, 50000);
+  }
+  
+  console.log('Running bidirectional streaming pipeline...');
+  console.log('JSON → CSV → JSON roundtrip');
+  
+  const startTime = Date.now();
+  
+  try {
+    // Step 1: JSON to CSV
+    console.log('\nStep 1: Converting JSON to CSV...');
+    
+    const jsonToCsvOptions = {
+      delimiter: ',',
+      includeHeaders: true,
+      preventCsvInjection: true
+    };
+    
+    // For simplicity, we'll use the regular conversion
+    // In production, you would use proper streaming
+    const jsonData = require(inputFile);
+    const csvData = jtcsv.jsonToCsv(jsonData, jsonToCsvOptions);
+    
+    await fs.promises.writeFile(tempFile, csvData, 'utf8');
+    
+    const step1Time = Date.now() - startTime;
+    console.log(`  ✓ Step 1 completed in ${step1Time}ms`);
+    
+    // Step 2: CSV to JSON
+    console.log('\nStep 2: Converting CSV to JSON...');
+    
+    const csvToJsonOptions = {
+      delimiter: ',',
+      hasHeaders: true,
+      parseNumbers: true,
+      parseBooleans: true
+    };
+    
+    const finalData = await jtcsv.readCsvAsJson(tempFile, csvToJsonOptions);
+    
+    await fs.promises.writeFile(
+      outputFile,
+      JSON.stringify(finalData, null, 2),
+      'utf8'
+    );
+    
+    const totalTime = Date.now() - startTime;
+    console.log(`  ✓ Step 2 completed in ${totalTime - step1Time}ms`);
+    
+    // Verification
+    console.log('\nVerification:');
+    console.log(`  Original records: ${jsonData.length}`);
+    console.log(`  Final records: ${finalData.length}`);
+    
+    // Check if data survived roundtrip
+    const sampleOriginal = jsonData[0];
+    const sampleFinal = finalData[0];
+    
+    console.log('\nSample comparison (first record):');
+    console.log('  Original:', JSON.stringify(sampleOriginal).substring(0, 100) + '...');
+    console.log('  Final:   ', JSON.stringify(sampleFinal).substring(0, 100) + '...');
+    
+    // Cleanup temp file
+    await fs.promises.unlink(tempFile).catch(() => {});
+    
+    console.log(`\n✓ Bidirectional streaming completed in ${totalTime}ms`);
+    
+  } catch (error) {
+    console.error('Error:', error.message);
+    
+    // Cleanup on error
+    try {
+      await fs.promises.unlink(tempFile);
+    } catch (_e) {
+      // Ignore cleanup errors
+    }
+  }
+}
+
+async function main() {
+  console.log('='.repeat(60));
+  console.log('jtcsv Streaming Examples');
+  console.log('='.repeat(60));
+  
+  // Create examples directory
+  const examplesDir = './examples';
+  if (!fs.existsSync(examplesDir)) {
+    fs.mkdirSync(examplesDir, { recursive: true });
+  }
+  
+  try {
+    await exampleJsonToCsvStreaming();
+    await exampleCsvToJsonStreaming();
+    await exampleBidirectionalStreaming();
+    
+    console.log('\n' + '='.repeat(60));
+    console.log('All examples completed successfully!');
+    console.log('='.repeat(60));
+    
+    console.log('\nTry these commands:');
+    console.log('  • Launch TUI:        npx jtcsv tui');
+    console.log('  • Convert JSON:      npx jtcsv json2csv examples/large-data.json output.csv');
+    console.log('  • Convert CSV:       npx jtcsv csv2json examples/large-data.csv output.json');
+    console.log('  • Streaming mode:    npx jtcsv stream json2csv examples/large-data.json streamed.csv');
+    
+  } catch (error) {
+    console.error('\nError running examples:', error.message);
+    process.exit(1);
+  }
+}
+
+// Run examples
+if (require.main === module) {
+  main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+  });
+}
+
+export default {
+  generateLargeJsonFile,
+  exampleJsonToCsvStreaming,
+  exampleCsvToJsonStreaming,
+  exampleBidirectionalStreaming
+};

package/examples/web-workers-advanced.ts

@@ -0,0 +1,28 @@
+// Advanced Web Workers usage (browser example)
+// Requires jtcsv loaded in the browser (UMD or ESM).
+
+async function runWorkerDemo(file) {
+  if (!window.jtcsv) {
+    throw new Error('jtcsv is not available on window');
+  }
+
+  const pool = window.jtcsv.createWorkerPool({
+    workerCount: 4,
+    maxQueueSize: 50,
+    autoScale: true
+  });
+
+  const result = await window.jtcsv.parseCSVWithWorker(file, {
+    delimiter: ',',
+    parseNumbers: true
+  }, (progress) => {
+    console.log(`Processed ${progress.processed} rows (${progress.percentage.toFixed(1)}%)`);
+  }, pool);
+
+  console.log('Rows:', result.length);
+  return result;
+}
+
+// Example usage in the browser:
+// const file = document.querySelector('input[type="file"]').files[0];
+// runWorkerDemo(file);

package/index.d.ts

@@ -1,5 +1,4 @@
-declare module 'jtcsv' {
-  import { Readable, Writable, Transform } from 'stream';
+import { Readable, Writable, Transform } from 'stream';
 
   // JSON to CSV interfaces
   export interface JsonToCsvOptions {
@@ -649,4 +648,3 @@ declare module 'jtcsv' {
   export function createTsvToJsonStream(
     options?: TsvOptions
   ): TransformStream;
-}

package/index.js

@@ -1,3 +1,4 @@
+// @ts-nocheck
 // Main entry point for the jtcsv module
 // Exports both JSON→CSV and CSV→JSON functions
 
@@ -9,6 +10,8 @@ const streamJsonToCsvModule = require('./stream-json-to-csv');
 const streamCsvToJsonModule = require('./stream-csv-to-json');
 const ndjsonParser = require('./src/formats/ndjson-parser');
 const tsvParser = require('./src/formats/tsv-parser');
+const zodAdapter = require('./src/utils/zod-adapter');
+const encodingSupport = require('./src/utils/encoding-support');
 
 // Combine all exports
 module.exports = {
@@ -64,5 +67,16 @@ module.exports = {
   createTsvToJsonStream: tsvParser.createTsvToJsonStream,
 
   // Error classes
-  ...errorsModule
+  ...errorsModule,
+
+  // Schema validation adapters (optional dependencies)
+  createZodValidationHook: zodAdapter.createZodValidationHook,
+  createYupValidationHook: zodAdapter.createYupValidationHook,
+  createValidatedParser: zodAdapter.createValidatedParser,
+
+  // Encoding detection and conversion
+  detectEncoding: encodingSupport.detectEncoding,
+  convertToUtf8: encodingSupport.convertToUtf8,
+  autoDetectAndConvert: encodingSupport.autoDetectAndConvert,
+  csvToJsonWithEncoding: encodingSupport.csvToJsonWithEncoding
 };