jtcsv 2.2.8 → 3.1.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('jtcsv');
+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 → streaming-example.ts}

@@ -7,10 +7,10 @@
  * and real-time progress monitoring.
  */
 
-const fs = require('fs');
-const path = require('path');
-const { pipeline } = require('stream/promises');
-const jtcsv = require('../index.js');
+import fs from "fs";
+import path from "path";
+const {  pipeline  } = await import("stream/promises");
+import jtcsv from "jtcsv";
 
 async function generateLargeJsonFile(filePath, recordCount) {
   console.log(`Generating ${recordCount} records...`);
@@ -83,7 +83,8 @@ async function exampleJsonToCsvStreaming() {
     let buffer = '';
     let recordCount = 0;
     
-    const jsonStream = new (require('stream').Transform)({
+    const streamModule = require("stream");
+    const jsonStream = new streamModule.Transform({
       objectMode: true,
       transform(chunk, encoding, callback) {
         buffer += chunk;
@@ -223,7 +224,7 @@ async function exampleCsvToJsonStreaming() {
     let firstRecord = true;
     
     // Custom transform to format JSON array
-    const arrayFormatter = new (require('stream').Transform)({
+    const arrayFormatter = (require("stream").Transform)({
       objectMode: true,
       transform(chunk, encoding, callback) {
         const jsonRecord = JSON.stringify(chunk);
@@ -364,7 +365,9 @@ async function exampleBidirectionalStreaming() {
     // Cleanup on error
     try {
       await fs.promises.unlink(tempFile);
-    } catch (e) {}
+    } catch (_e) {
+      // Ignore cleanup errors
+    }
   }
 }
 
@@ -408,12 +411,9 @@ if (require.main === module) {
   });
 }
 
-module.exports = {
+export default {
   generateLargeJsonFile,
   exampleJsonToCsvStreaming,
   exampleCsvToJsonStreaming,
   exampleBidirectionalStreaming
-};
-
-
-
+};

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 {
@@ -13,12 +12,18 @@ declare module 'jtcsv' {
     template?: Record<string, any>;
     /** Maximum number of records to process (optional, no limit by default) */
     maxRecords?: number;
-    /** Prevent CSV injection attacks by escaping formulas (default: true) */
-    preventCsvInjection?: boolean;
-    /** Ensure RFC 4180 compliance (proper quoting, line endings) (default: true) */
-    rfc4180Compliant?: boolean;
-    /** JSON schema for data validation and formatting */
-    schema?: Record<string, any>;
+  /** Prevent CSV injection attacks by escaping formulas (default: true) */
+  preventCsvInjection?: boolean;
+  /** Ensure RFC 4180 compliance (proper quoting, line endings) (default: true) */
+  rfc4180Compliant?: boolean;
+  /** Normalize excessive quotes in JSON string values before CSV export (default: true) */
+  normalizeQuotes?: boolean;
+  /** JSON schema for data validation and formatting */
+  schema?: Record<string, any>;
+    /** Warn when record count exceeds this threshold (default: 1000000) */
+    memoryWarningThreshold?: number;
+    /** Safety limit for in-memory conversion (default: 5000000). Set to Infinity to disable. */
+    memoryLimit?: number;
   }
 
   export interface SaveAsCsvOptions extends JsonToCsvOptions {
@@ -50,6 +55,18 @@ declare module 'jtcsv' {
     useFastPath?: boolean;
     /** Fast-path output mode (default: 'objects') */
     fastPathMode?: 'objects' | 'compact' | 'stream';
+    /** Error recovery strategy for row-level errors (default: 'throw') */
+    onError?: 'skip' | 'warn' | 'throw';
+    /** Custom error handler for row-level errors */
+    errorHandler?: (error: Error, line: string, lineNumber: number) => void;
+    /** Attempt to repair shifted rows with trailing empty fields (default: true) */
+    repairRowShifts?: boolean;
+    /** Normalize excessive quotes in parsed fields (default: true) */
+    normalizeQuotes?: boolean;
+    /** Warn when row count exceeds this threshold (default: 1000000) */
+    memoryWarningThreshold?: number;
+    /** Safety limit for in-memory conversion (default: 5000000). Set to Infinity to disable. */
+    memoryLimit?: number;
   }
 
   // JSON save interfaces
@@ -171,41 +188,117 @@ declare module 'jtcsv' {
   }
 
   // Error classes
+  export type ErrorContextValue = Record<string, any> | string | null;
+
+  export interface ErrorMeta {
+    hint?: string;
+    docs?: string;
+    context?: ErrorContextValue;
+    originalError?: Error;
+  }
+
   export class JtcsvError extends Error {
     code: string;
-    constructor(message: string, code?: string);
+    hint?: string;
+    docs?: string;
+    context?: ErrorContextValue;
+    originalError?: Error;
+    constructor(message: string, code?: string, meta?: ErrorMeta);
   }
 
   export class ValidationError extends JtcsvError {
-    constructor(message: string);
+    constructor(message: string, meta?: ErrorMeta);
   }
 
   export class SecurityError extends JtcsvError {
-    constructor(message: string);
+    constructor(message: string, meta?: ErrorMeta);
   }
 
   export class FileSystemError extends JtcsvError {
     originalError?: Error;
-    constructor(message: string, originalError?: Error);
+    constructor(message: string, originalError?: Error | null, meta?: ErrorMeta);
   }
 
   export class ParsingError extends JtcsvError {
     lineNumber?: number;
     column?: number;
-    constructor(message: string, lineNumber?: number, column?: number);
+    context?: ErrorContextValue;
+    expected?: string | null;
+    actual?: string | null;
+    originalMessage?: string;
+    constructor(
+      message: string,
+      lineNumber?: number | null,
+      column?: number | null,
+      context?: string | null,
+      expected?: string | null,
+      actual?: string | null,
+      meta?: ErrorMeta
+    );
   }
 
   export class LimitError extends JtcsvError {
-    limit: number;
-    actual: number;
-    constructor(message: string, limit: number, actual: number);
+    limit: any;
+    actual: any;
+    constructor(message: string, limit: any, actual: any, meta?: ErrorMeta);
   }
 
   export class ConfigurationError extends JtcsvError {
-    constructor(message: string);
+    constructor(message: string, meta?: ErrorMeta);
   }
 
+  export const ERROR_CODES: {
+    JTCSV_ERROR: string;
+    VALIDATION_ERROR: string;
+    SECURITY_ERROR: string;
+    FILE_SYSTEM_ERROR: string;
+    PARSING_ERROR: string;
+    LIMIT_ERROR: string;
+    CONFIGURATION_ERROR: string;
+    INVALID_INPUT: string;
+    SECURITY_VIOLATION: string;
+    FILE_NOT_FOUND: string;
+    PARSE_FAILED: string;
+    SIZE_LIMIT: string;
+    INVALID_CONFIG: string;
+    UNKNOWN_ERROR: string;
+    STREAM_CREATION_ERROR: string;
+    STREAM_PROCESSING_ERROR: string;
+  };
+
+  export type ErrorCode = typeof ERROR_CODES[keyof typeof ERROR_CODES];
+
   // Utility functions
+  export function createDetailedErrorMessage(
+    baseMessage: string,
+    details?: {
+      lineNumber?: number;
+      column?: number;
+      context?: string;
+      expected?: string;
+      actual?: string;
+      suggestion?: string;
+      codeSnippet?: string;
+      hint?: string;
+      docs?: string;
+    }
+  ): string;
+
+  export class ErrorContext {
+    lineNumber(line: number): this;
+    column(col: number): this;
+    context(ctx: string): this;
+    expected(exp: string): this;
+    actual(act: string): this;
+    suggestion(sugg: string): this;
+    codeSnippet(snippet: string): this;
+    hint(text: string): this;
+    docs(link: string): this;
+    buildMessage(baseMessage: string): string;
+    throwParsingError(baseMessage: string): never;
+    throwValidationError(baseMessage: string): never;
+  }
+
   export function createErrorMessage(type: string, details: string): string;
   export function handleError(error: Error, context?: Record<string, any>): void;
   export function safeExecute<T>(
@@ -218,6 +311,16 @@ declare module 'jtcsv' {
     errorType: string,
     context?: Record<string, any>
   ): T;
+  export function safeExecuteSync<T>(
+    fn: () => T,
+    errorType: string,
+    context?: Record<string, any>
+  ): T;
+  export function safeExecuteAsync<T>(
+    fn: () => Promise<T>,
+    errorType: string,
+    context?: Record<string, any>
+  ): Promise<T>;
 
   /**
    * Convert JSON array to CSV string
@@ -320,6 +423,17 @@ declare module 'jtcsv' {
     options?: CsvToJsonOptions
   ): Promise<Record<string, any>[]>;
 
+  /**
+   * Read CSV file and convert it to JSON array (normalized naming alias)
+   * @param filePath Path to CSV file
+   * @param options Conversion options
+   * @returns Promise that resolves to JSON array
+   */
+  export function csvToJsonFile(
+    filePath: string,
+    options?: CsvToJsonOptions
+  ): Promise<Record<string, any>[]>;
+
   /**
    * Synchronously read CSV file and convert it to JSON array
    * @param filePath Path to CSV file
@@ -334,6 +448,17 @@ declare module 'jtcsv' {
     options?: CsvToJsonOptions
   ): Record<string, any>[];
 
+  /**
+   * Synchronously read CSV file and convert it to JSON array (normalized naming alias)
+   * @param filePath Path to CSV file
+   * @param options Conversion options
+   * @returns JSON array
+   */
+  export function csvToJsonFileSync(
+    filePath: string,
+    options?: CsvToJsonOptions
+  ): Record<string, any>[];
+
   /**
    * Auto-detect CSV delimiter from content
    * @param csv CSV content string
@@ -451,6 +576,15 @@ declare module 'jtcsv' {
     options?: CsvToJsonStreamOptions
   ): Transform;
 
+  /**
+   * Creates a transform stream that converts CSV chunks to JSON objects (normalized naming alias)
+   * @param options Configuration options
+   * @returns Transform stream
+   */
+  export function csvToJsonStream(
+    options?: CsvToJsonStreamOptions
+  ): Transform;
+
   /**
    * Converts a readable stream of CSV text to JSON objects
    * @param inputStream Readable stream of CSV text
@@ -475,6 +609,17 @@ declare module 'jtcsv' {
     options?: CsvToJsonStreamOptions
   ): Promise<Readable>;
 
+  /**
+   * Reads CSV file and converts it to JSON using streaming (normalized naming alias)
+   * @param filePath Path to CSV file
+   * @param options Configuration options
+   * @returns Readable stream of JSON objects
+   */
+  export function csvFileToJsonStream(
+    filePath: string,
+    options?: CsvToJsonStreamOptions
+  ): Promise<Readable>;
+
   /**
    * Creates a writable stream that collects JSON objects into an array
    * @returns Writable stream that collects data
@@ -649,4 +794,28 @@ declare module 'jtcsv' {
   export function createTsvToJsonStream(
     options?: TsvOptions
   ): TransformStream;
-}
+
+  // Built-in validators
+  export function isEmail(value: string): boolean;
+  export function isUrl(value: string): boolean;
+  export function isDate(value: string | Date): boolean;
+  export const validators: {
+    isEmail: typeof isEmail;
+    isUrl: typeof isUrl;
+    isDate: typeof isDate;
+  };
+
+  // Batch helpers (Node.js)
+  export function createBatchProcessor<T, R>(
+    processor: (batch: T[]) => Promise<R[]> | R[],
+    options?: { batchSize?: number; parallelism?: number }
+  ): (items: T[]) => AsyncGenerator<R>;
+
+  export const asyncIterUtils: {
+    mapConcurrent<T, R>(
+      iterator: AsyncIterable<T>,
+      mapper: (item: T) => Promise<R> | R,
+      concurrency?: number
+    ): AsyncGenerator<R>;
+    batch<T>(iterator: AsyncIterable<T>, size?: number): AsyncGenerator<T[]>;
+  };