jtcsv 2.2.8 → 3.1.0

package/examples/async-multithreaded-example.ts

@@ -0,0 +1,335 @@
+/**
+ * Пример использования асинхронных многопоточных функций jtcsv
+ * 
+ * Демонстрация:
+ * 1. Асинхронные версии функций
+ * 2. Многопоточная обработка через Worker Pool
+ * 3. Оптимизация производительности
+ */
+
+import { 
+  csvToJson, 
+  csvToJsonAsync,
+  jsonToCsv,
+  jsonToCsvAsync,
+  saveAsJsonAsync,
+  streamCsvToJsonAsync,
+  streamJsonToCsvAsync,
+  JtcsvError,
+  ValidationError
+} from '../index-core';
+
+import {
+  csvToJsonMultithreaded,
+  jsonToCsvMultithreaded,
+  benchmarkMultithreaded,
+  optimizeChunkSize,
+  getResourceUsage
+} from '../src/workers/csv-multithreaded';
+
+/**
+ * Пример 1: Базовое асинхронное использование
+ */
+async function exampleBasicAsync() {
+  console.log('=== Пример 1: Базовое асинхронное использование ===\n');
+  
+  // Создаем тестовые данные
+  const testData = [
+    { id: 1, name: 'Alice', age: 30, email: 'alice@example.com' },
+    { id: 2, name: 'Bob', age: 25, email: 'bob@example.com' },
+    { id: 3, name: 'Charlie', age: 35, email: 'charlie@example.com' }
+  ];
+  
+  // 1. Конвертация JSON в CSV (асинхронно)
+  console.log('1. Конвертация JSON в CSV (асинхронно):');
+  const csv = await jsonToCsvAsync(testData, {
+    delimiter: ',',
+    includeHeaders: true,
+    onProgress: (progress) => {
+      console.log(`  Прогресс: ${progress.percentage}% (${progress.processed}/${progress.total})`);
+    }
+  });
+  console.log(`Результат:\n${csv}\n`);
+  
+  // 2. Конвертация CSV в JSON (асинхронно)
+  console.log('2. Конвертация CSV в JSON (асинхронно):');
+  const json = await csvToJsonAsync(csv, {
+    delimiter: ',',
+    hasHeaders: true,
+    parseNumbers: true,
+    onProgress: (progress) => {
+      console.log(`  Прогресс: ${progress.percentage}% (${progress.processed}/${progress.total})`);
+    }
+  });
+  console.log(`Результат:`, JSON.stringify(json, null, 2), '\n');
+  
+  // 3. Сохранение JSON в файл (асинхронно)
+  console.log('3. Сохранение JSON в файл (асинхронно):');
+  try {
+    await saveAsJsonAsync(testData, './test-output.json', {
+      prettyPrint: true,
+      maxSize: 1024 * 1024 // 1MB
+    });
+    console.log('  Файл успешно сохранен: ./test-output.json\n');
+  } catch (error) {
+    if (error instanceof JtcsvError) {
+      console.log(`  Ошибка сохранения: ${error.message}\n`);
+    }
+  }
+}
+
+/**
+ * Пример 2: Многопоточная обработка больших данных
+ */
+async function exampleMultithreaded() {
+  console.log('=== Пример 2: Многопоточная обработка больших данных ===\n');
+  
+  // Создаем большой CSV файл для тестирования
+  const largeCsv = generateLargeCsv(10000);
+  
+  console.log('Размер данных:', formatBytes(largeCsv.length));
+  console.log('Количество строк: 10,000\n');
+  
+  // 1. Однопоточная обработка
+  console.log('1. Однопоточная обработка:');
+  const singleThreadStart = Date.now();
+  const singleThreadResult = await csvToJsonAsync(largeCsv, {
+    delimiter: ',',
+    hasHeaders: true,
+    useWorkers: false // Отключаем многопоточность
+  });
+  const singleThreadTime = Date.now() - singleThreadStart;
+  console.log(`  Время выполнения: ${singleThreadTime}ms\n`);
+  
+  // 2. Многопоточная обработка
+  console.log('2. Многопоточная обработка:');
+  const multiThreadStart = Date.now();
+  const multiThreadResult = await csvToJsonMultithreaded(largeCsv, {
+    delimiter: ',',
+    hasHeaders: true,
+    useWorkers: true,
+    workerCount: 4, // Используем 4 worker'а
+    chunkSize: optimizeChunkSize(10000, 4),
+    onProgress: (progress) => {
+      process.stdout.write(`\r  Прогресс: ${progress.percentage}% (${progress.processed}/${progress.total})`);
+    }
+  });
+  const multiThreadTime = Date.now() - multiThreadStart;
+  console.log(`\n  Время выполнения: ${multiThreadTime}ms`);
+  console.log(`  Ускорение: ${(singleThreadTime / multiThreadTime).toFixed(2)}x\n`);
+  
+  // 3. Бенчмарк производительности
+  console.log('3. Бенчмарк производительности:');
+  const benchmark = await benchmarkMultithreaded(largeCsv, 5);
+  console.log(`  Однопоточное время: ${benchmark.singleThread}ms`);
+  console.log(`  Многопоточное время: ${benchmark.multiThread}ms`);
+  console.log(`  Ускорение: ${benchmark.speedup.toFixed(2)}x`);
+  console.log(`  Эффективность: ${benchmark.efficiency.toFixed(1)}%\n`);
+  
+  // 4. Мониторинг ресурсов
+  console.log('4. Мониторинг ресурсов:');
+  const resources = getResourceUsage();
+  console.log(`  Использование памяти:`, formatBytes(resources.memoryUsage.heapUsed));
+  console.log(`  Всего worker'ов: ${resources.workerStats.totalWorkers}`);
+  console.log(`  Активных worker'ов: ${resources.workerStats.activeWorkers}`);
+  console.log(`  Выполнено задач: ${resources.workerStats.completedTasks}\n`);
+}
+
+/**
+ * Пример 3: Streaming с асинхронной обработкой
+ */
+async function exampleStreaming() {
+  console.log('=== Пример 3: Streaming с асинхронной обработкой ===\n');
+  
+  // Создаем большой массив данных
+  const largeData = generateLargeJson(5000);
+  
+  console.log('Размер данных:', largeData.length, 'записей\n');
+  
+  // 1. Streaming конвертация JSON в CSV
+  console.log('1. Streaming конвертация JSON в CSV:');
+  const csvStream = await streamJsonToCsvAsync(largeData, {
+    delimiter: ',',
+    includeHeaders: true,
+    bufferSize: 1024 * 64 // 64KB буфер
+  });
+  
+  let csvChunks: string[] = [];
+  for await (const chunk of csvStream) {
+    csvChunks.push(chunk);
+    process.stdout.write(`\r  Получено чанков: ${csvChunks.length}, размер: ${formatBytes(chunk.length)}`);
+  }
+  console.log(`\n  Общий размер CSV: ${formatBytes(csvChunks.join('').length)}\n`);
+  
+  // 2. Streaming конвертация CSV в JSON
+  console.log('2. Streaming конвертация CSV в JSON:');
+  const csvData = csvChunks.join('');
+  const jsonStream = await streamCsvToJsonAsync(csvData, {
+    delimiter: ',',
+    hasHeaders: true,
+    bufferSize: 1024 * 64
+  });
+  
+  let jsonRecords = 0;
+  for await (const record of jsonStream) {
+    jsonRecords++;
+    if (jsonRecords % 1000 === 0) {
+      process.stdout.write(`\r  Обработано записей: ${jsonRecords}`);
+    }
+  }
+  console.log(`\n  Всего обработано записей: ${jsonRecords}\n`);
+}
+
+/**
+ * Пример 4: Обработка ошибок и валидация
+ */
+async function exampleErrorHandling() {
+  console.log('=== Пример 4: Обработка ошибок и валидация ===\n');
+  
+  // 1. Некорректные данные
+  console.log('1. Обработка некорректных данных:');
+  try {
+    await csvToJsonAsync('invalid,csv\n1,2,3\n4,5', {
+      delimiter: ',',
+      hasHeaders: true
+    });
+  } catch (error) {
+    if (error instanceof ValidationError) {
+      console.log(`  Поймана ValidationError: ${error.message}`);
+    } else if (error instanceof JtcsvError) {
+      console.log(`  Поймана JtcsvError: ${error.message} (код: ${error.code})`);
+    }
+  }
+  console.log();
+  
+  // 2. Безопасное выполнение с обработкой ошибок
+  console.log('2. Безопасное выполнение:');
+  const result = await csvToJsonAsync('id,name\n1,Alice\n2,Bob', {
+    delimiter: ',',
+    hasHeaders: true,
+    maxRows: 1 // Ограничиваем количество строк
+  }).catch(error => {
+    console.log(`  Ошибка обработана: ${error.message}`);
+    return [];
+  });
+  console.log(`  Результат: ${result.length} записей\n`);
+  
+  // 3. Валидация путей файлов
+  console.log('3. Валидация путей файлов:');
+  try {
+    // Попытка сохранить в системную директорию
+    await saveAsJsonAsync([{ test: 'data' }], 'C:\\Windows\\test.json', {
+      validatePath: true
+    });
+  } catch (error) {
+    if (error instanceof SecurityError) {
+      console.log(`  Поймана SecurityError: ${error.message}`);
+    }
+  }
+}
+
+/**
+ * Генератор большого CSV файла
+ */
+function generateLargeCsv(rows: number): string {
+  const headers = ['id', 'name', 'email', 'age', 'salary', 'department', 'join_date', 'active'];
+  let csv = headers.join(',') + '\n';
+  
+  for (let i = 1; i <= rows; i++) {
+    const row = [
+      i,
+      `User${i}`,
+      `user${i}@example.com`,
+      Math.floor(Math.random() * 50) + 20,
+      Math.floor(Math.random() * 100000) + 30000,
+      ['Engineering', 'Marketing', 'Sales', 'HR'][Math.floor(Math.random() * 4)],
+      `2023-${String(Math.floor(Math.random() * 12) + 1).padStart(2, '0')}-${String(Math.floor(Math.random() * 28) + 1).padStart(2, '0')}`,
+      Math.random() > 0.5 ? 'true' : 'false'
+    ];
+    csv += row.join(',') + '\n';
+  }
+  
+  return csv;
+}
+
+/**
+ * Генератор большого JSON массива
+ */
+function generateLargeJson(rows: number): any[] {
+  const departments = ['Engineering', 'Marketing', 'Sales', 'HR', 'Finance', 'Operations'];
+  const data = [];
+  
+  for (let i = 1; i <= rows; i++) {
+    data.push({
+      id: i,
+      name: `User${i}`,
+      email: `user${i}@example.com`,
+      age: Math.floor(Math.random() * 50) + 20,
+      salary: Math.floor(Math.random() * 100000) + 30000,
+      department: departments[Math.floor(Math.random() * departments.length)],
+      join_date: `2023-${String(Math.floor(Math.random() * 12) + 1).padStart(2, '0')}-${String(Math.floor(Math.random() * 28) + 1).padStart(2, '0')}`,
+      active: Math.random() > 0.5,
+      metadata: {
+        level: Math.floor(Math.random() * 5) + 1,
+        skills: ['JavaScript', 'TypeScript', 'Node.js'].slice(0, Math.floor(Math.random() * 3) + 1)
+      }
+    });
+  }
+  
+  return data;
+}
+
+/**
+ * Форматирование байтов в читаемый вид
+ */
+function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 Bytes';
+  
+  const k = 1024;
+  const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+}
+
+/**
+ * Основная функция
+ */
+async function main() {
+  console.log('🚀 ДЕМОНСТРАЦИЯ АСИНХРОННЫХ МНОГОПОТОЧНЫХ ФУНКЦИЙ JTCSV\n');
+  console.log('='.repeat(80) + '\n');
+  
+  try {
+    await exampleBasicAsync();
+    await exampleMultithreaded();
+    await exampleStreaming();
+    await exampleErrorHandling();
+    
+    console.log('='.repeat(80));
+    console.log('\n✅ Все примеры успешно выполнены!');
+    console.log('\n📊 ИТОГИ:');
+    console.log('  • Реализованы асинхронные версии всех основных функций');
+    console.log('  • Создана система Worker Pool для многопоточной обработки');
+    console.log('  • Добавлена оптимизация размера чанков и мониторинг ресурсов');
+    console.log('  • Сохранена обратная совместимость с синхронным API');
+    console.log('  • Улучшена производительность для больших данных');
+    
+  } catch (error) {
+    console.error('\n❌ Ошибка выполнения примеров:', error);
+    process.exit(1);
+  }
+}
+
+// Запуск демонстрации
+if (require.main === module) {
+  main().catch(console.error);
+}
+
+export {
+  exampleBasicAsync,
+  exampleMultithreaded,
+  exampleStreaming,
+  exampleErrorHandling,
+  generateLargeCsv,
+  generateLargeJson
+};

package/examples/cli-advanced-usage.md

@@ -0,0 +1,290 @@
+# Расширенное использование CLI jtcsv
+Current version: 3.1.0
+
+
+Этот документ описывает расширенные возможности CLI jtcsv, включая новые функции, добавленные в рамках улучшений проекта.
+
+## Новые возможности CLI
+
+### 1. Обработка вложенных объектов (Flattening)
+
+CLI теперь поддерживает автоматическое разворачивание вложенных объектов с помощью опции `--flatten`.
+
+**Примеры:**
+
+```bash
+# Развернуть вложенные объекты с разделителем по умолчанию (.)
+jtcsv json-to-csv data.json --output result.csv --flatten
+
+# Использовать пользовательский разделитель
+jtcsv json-to-csv data.json --output result.csv --flatten --flatten-separator "_"
+
+# Установить максимальную глубину разворачивания
+jtcsv json-to-csv data.json --output result.csv --flatten --flatten-max-depth 4
+
+# Комбинированные опции
+jtcsv json-to-csv data.json --output result.csv \
+  --flatten \
+  --flatten-separator ":" \
+  --flatten-max-depth 5 \
+  --delimiter "," \
+  --include-headers
+```
+
+### 2. Пакетная обработка файлов
+
+CLI поддерживает пакетную обработку нескольких файлов:
+
+```bash
+# Конвертация всех JSON файлов в директории
+jtcsv batch-convert ./input/*.json --output-dir ./output --format csv
+
+# Конвертация всех CSV файлов в JSON
+jtcsv batch-convert ./input/*.csv --output-dir ./output --format json
+
+# С фильтрацией по размеру
+jtcsv batch-convert ./input/*.json --output-dir ./output --min-size 1KB --max-size 10MB
+```
+
+### 3. Валидация данных
+
+```bash
+# Валидация CSV файла
+jtcsv validate input.csv --schema schema.json
+
+# Валидация JSON файла
+jtcsv validate data.json --schema schema.json
+
+# Проверка структуры без схемы
+jtcsv validate-structure data.json --check-consistency
+```
+
+### 4. Статистика и анализ
+
+```bash
+# Получить статистику о CSV файле
+jtcsv stats input.csv
+
+# Анализ структуры JSON файла
+jtcsv analyze-structure data.json
+
+# Проверка производительности
+jtcsv benchmark input.csv --iterations 10 --output benchmark.json
+```
+
+### 5. Потоковая обработка больших файлов
+
+```bash
+# Потоковая конвертация больших файлов
+jtcsv stream-convert large-input.csv --output large-output.json --chunk-size 10000
+
+# Параллельная обработка
+jtcsv parallel-convert huge-file.csv --output result.json --workers 4
+
+# Мониторинг прогресса
+jtcsv convert big-data.json --output big-data.csv --progress --progress-interval 1000
+```
+
+## Полный список новых опций
+
+### Опции flattening:
+- `--flatten` - Включить разворачивание вложенных объектов
+- `--flatten-separator` - Разделитель для развернутых ключей (по умолчанию: ".")
+- `--flatten-max-depth` - Максимальная глубина разворачивания (по умолчанию: 3)
+- `--array-handling` - Стратегия обработки массивов: "stringify", "join", "expand" (по умолчанию: "stringify")
+
+### Опции пакетной обработки:
+- `--batch-size` - Размер пакета для обработки
+- `--parallel` - Количество параллельных процессов
+- `--continue-on-error` - Продолжать при ошибках
+- `--log-file` - Файл для логов
+
+### Опции валидации:
+- `--schema` - JSON схема для валидации
+- `--strict` - Строгая валидация
+- `--report-format` - Формат отчета: "json", "text", "html"
+
+## Примеры реального использования
+
+### Пример 1: Обработка сложных JSON структур
+
+```bash
+# Исходный JSON с вложенными объектами
+cat > complex-data.json << 'EOF'
+[
+  {
+    "id": 1,
+    "user": {
+      "name": "John Doe",
+      "contact": {
+        "email": "john@example.com",
+        "phone": "+1234567890"
+      }
+    },
+    "orders": [
+      {"id": "A1", "amount": 100},
+      {"id": "A2", "amount": 200}
+    ]
+  }
+]
+EOF
+
+# Конвертация с flattening
+jtcsv json-to-csv complex-data.json --output flattened.csv \
+  --flatten \
+  --flatten-separator "_" \
+  --delimiter ","
+
+# Результат:
+# id,user_name,user_contact_email,user_contact_phone,orders
+# 1,John Doe,john@example.com,+1234567890,"[{""id"":""A1"",""amount"":100},{""id"":""A2"",""amount"":200}]"
+```
+
+### Пример 2: Пакетная обработка с валидацией
+
+```bash
+# Создание схемы валидации
+cat > schema.json << 'EOF'
+{
+  "type": "object",
+  "properties": {
+    "id": { "type": "number" },
+    "name": { "type": "string" },
+    "email": { "type": "string", "format": "email" }
+  },
+  "required": ["id", "name"]
+}
+EOF
+
+# Пакетная обработка с валидацией
+jtcsv batch-convert ./data/*.json \
+  --output-dir ./processed \
+  --format csv \
+  --schema schema.json \
+  --parallel 4 \
+  --log-file ./processing.log
+```
+
+### Пример 3: Мониторинг и статистика
+
+```bash
+# Получение детальной статистики
+jtcsv stats large-dataset.csv \
+  --detailed \
+  --output-stats stats.json \
+  --include-samples
+
+# Анализ структуры
+jtcsv analyze-structure complex-data.json \
+  --output-analysis analysis.md \
+  --include-recommendations
+
+# Бенчмарк производительности
+jtcsv benchmark test-data.csv \
+  --iterations 5 \
+  --warmup 2 \
+  --output-format json \
+  --compare-with papaparse csvtojson
+```
+
+## Интеграция с CI/CD
+
+CLI может быть использован в CI/CD пайплайнах:
+
+```yaml
+# .github/workflows/data-processing.yml
+name: Data Processing Pipeline
+
+on:
+  push:
+    paths:
+      - 'data/**'
+
+jobs:
+  process-data:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+          
+      - name: Install jtcsv
+        run: npm install -g jtcsv
+        
+      - name: Validate data
+        run: |
+          jtcsv validate ./data/input.csv \
+            --schema ./schemas/data-schema.json \
+            --report-format json \
+            --output validation-report.json
+            
+      - name: Process data
+        run: |
+          jtcsv batch-convert ./data/*.csv \
+            --output-dir ./processed \
+            --format json \
+            --flatten \
+            --parallel 2
+            
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v3
+        with:
+          name: processed-data
+          path: ./processed/
+```
+
+## Советы по производительности
+
+1. **Используйте потоковую обработку для больших файлов:**
+   ```bash
+   jtcsv stream-convert huge-file.csv --chunk-size 50000
+   ```
+
+2. **Настройте размер пакета для вашего железа:**
+   ```bash
+   jtcsv batch-convert *.json --batch-size 1000 --parallel $(nproc)
+   ```
+
+3. **Используйте кэширование для повторяющихся операций:**
+   ```bash
+   jtcsv convert data.json --cache --cache-dir ./cache
+   ```
+
+4. **Мониторинг использования памяти:**
+   ```bash
+   jtcsv convert large-data.csv --memory-limit 2GB --progress
+   ```
+
+## Устранение неполадок
+
+### Проблема: Ошибка памяти при обработке больших файлов
+**Решение:** Используйте потоковую обработку
+```bash
+jtcsv stream-convert large-file.csv --chunk-size 10000
+```
+
+### Проблема: Медленная обработка
+**Решение:** Увеличьте параллелизм
+```bash
+jtcsv batch-convert *.json --parallel 4 --batch-size 5000
+```
+
+### Проблема: Сложные вложенные структуры
+**Решение:** Настройте flattening
+```bash
+jtcsv json-to-csv data.json --flatten --flatten-max-depth 5 --array-handling join
+```
+
+## Дополнительные ресурсы
+
+- [Документация jtcsv](https://github.com/yourusername/jtcsv)
+- [Примеры использования](https://github.com/yourusername/jtcsv/examples)
+- [Руководство по миграции](https://github.com/yourusername/jtcsv/docs/MIGRATION_GUIDE.md)
+- [Часто задаваемые вопросы](https://github.com/yourusername/jtcsv/docs/FAQ.md)
+
+---
+
+*Обновлено в рамках улучшений проекта jtcsv согласно jtcsv-winner-strategy.md*

package/examples/{cli-batch-processing.js → cli-batch-processing.ts}

@@ -1,38 +1,38 @@
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { spawnSync } = require('child_process');
-
-const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'jtcsv-batch-'));
-const inputDir = path.join(tempDir, 'input');
-const outputDir = path.join(tempDir, 'output');
-
-fs.mkdirSync(inputDir, { recursive: true });
-fs.mkdirSync(outputDir, { recursive: true });
-
-const sampleData = [
-  [{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }],
-  [{ id: 3, name: 'Max' }, { id: 4, name: 'Eva' }]
-];
-
-sampleData.forEach((data, idx) => {
-  const filePath = path.join(inputDir, `data-${idx + 1}.json`);
-  fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
-});
-
-const cliPath = path.join(__dirname, '..', 'bin', 'jtcsv.js');
-
-const result = spawnSync('node', [
-  cliPath,
-  'batch',
-  'json-to-csv',
-  path.join(inputDir, '*.json'),
-  outputDir,
-  '--delimiter=,'
-], { stdio: 'inherit' });
-
-if (result.status !== 0) {
-  process.exit(result.status);
-}
-
-console.log('Output files:', fs.readdirSync(outputDir));
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { spawnSync } from 'child_process';
+
+const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'jtcsv-batch-'));
+const inputDir = path.join(tempDir, 'input');
+const outputDir = path.join(tempDir, 'output');
+
+fs.mkdirSync(inputDir, { recursive: true });
+fs.mkdirSync(outputDir, { recursive: true });
+
+const sampleData = [
+  [{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }],
+  [{ id: 3, name: 'Max' }, { id: 4, name: 'Eva' }]
+];
+
+sampleData.forEach((data, idx) => {
+  const filePath = path.join(inputDir, `data-${idx + 1}.json`);
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+});
+
+const cliPath = path.join(__dirname, '..', 'bin', 'jtcsv.js');
+
+const result = spawnSync('node', [
+  cliPath,
+  'batch',
+  'json-to-csv',
+  path.join(inputDir, '*.json'),
+  outputDir,
+  '--delimiter=,'
+], { stdio: 'inherit' });
+
+if (result.status !== 0) {
+  process.exit(result.status);
+}
+
+console.log('Output files:', fs.readdirSync(outputDir));