jtcsv 2.2.7 → 3.0.0

package/plugins/fastify-plugin/index.ts

@@ -0,0 +1,443 @@
+/**
+ * Fastify plugin для JTCSV
+ * Плагин для автоматической конвертации CSV/JSON в Fastify приложениях
+ * 
+ * @version 1.0.0
+ * @date 2026-01-23
+ */
+
+const fp = require('fastify-plugin');
+import { csvToJson, csvToJsonAsync, jsonToCsv, jsonToCsvAsync } from '../../index-core';
+import { CsvToJsonOptions, JsonToCsvOptions } from '../../src/types';
+
+/**
+ * Опции плагина Fastify для JTCSV
+ */
+export interface JtcsvFastifyPluginOptions {
+  /** Префикс для маршрутов API */
+  prefix?: string;
+  /** Разделитель CSV по умолчанию */
+  delimiter?: string;
+  /** Включить fast-path engine */
+  enableFastPath?: boolean;
+  /** Защита от CSV инъекций */
+  preventCsvInjection?: boolean;
+  /** Соответствие стандарту RFC 4180 */
+  rfc4180Compliant?: boolean;
+}
+
+/**
+ * Статистика обработки
+ */
+interface ProcessingStats {
+  rows?: number;
+  size?: number;
+  processingTime: number;
+  inputSize?: number;
+  outputSize?: number;
+  conversion?: string;
+}
+
+/**
+ * Ответ API
+ */
+interface ApiResponse<T = any> {
+  success: boolean;
+  data?: T;
+  stats?: ProcessingStats;
+  error?: string;
+  code?: string;
+  details?: string;
+  format?: string;
+  inputFormat?: string;
+}
+
+/**
+ * Fastify plugin для JTCSV
+ * 
+ * @param fastify - Fastify instance
+ * @param options - Опции плагина
+ * @param next - Callback
+ * 
+ * @example
+ * // Базовое использование
+ * const fastify = require('fastify')();
+ * await fastify.register(require('@jtcsv/fastify'), {
+ *   prefix: '/api/convert'
+ * });
+ * 
+ * @example
+ * // С кастомными опциями
+ * await fastify.register(require('@jtcsv/fastify'), {
+ *   prefix: '/api',
+ *   enableFastPath: true,
+ *   delimiter: ';'
+ * });
+ */
+async function jtcsvFastifyPlugin(fastify: any, options: JtcsvFastifyPluginOptions = {}) {
+  const {
+    prefix = '/convert',
+    delimiter = ',',
+    enableFastPath = true,
+    preventCsvInjection = true,
+    rfc4180Compliant = true
+  } = options;
+
+  // Health check endpoint
+  fastify.get(`${prefix}/health`, async () => {
+    return {
+      service: 'jtcsv-fastify-plugin',
+      status: 'healthy',
+      version: '1.0.0',
+      timestamp: new Date().toISOString(),
+      features: {
+        csvToJson: true,
+        jsonToCsv: true,
+        fastPathEngine: enableFastPath,
+        csvInjectionProtection: preventCsvInjection,
+        streaming: true,
+        ndjson: true
+      }
+    };
+  });
+
+  // CSV to JSON endpoint
+  fastify.post(`${prefix}/csv-to-json`, {
+    schema: {
+      body: {
+        type: 'object',
+        required: ['csv'],
+        properties: {
+          csv: { type: 'string' },
+          delimiter: { type: 'string', default: delimiter },
+          parseNumbers: { type: 'boolean', default: true },
+          parseBooleans: { type: 'boolean', default: true },
+          useFastPath: { type: 'boolean', default: enableFastPath }
+        }
+      },
+      response: {
+        200: {
+          type: 'object',
+          properties: {
+            success: { type: 'boolean' },
+            data: { type: 'array' },
+            stats: {
+              type: 'object',
+              properties: {
+                rows: { type: 'number' },
+                processingTime: { type: 'number' }
+              }
+            }
+          }
+        }
+      }
+    }
+  }, async (request: any, reply: any) => {
+    const startTime = Date.now();
+    const {
+      csv,
+      delimiter: reqDelimiter = delimiter,
+      parseNumbers = true,
+      parseBooleans = true,
+      useFastPath = enableFastPath
+    } = request.body;
+
+    try {
+      const json = await csvToJsonAsync(csv, {
+        delimiter: reqDelimiter,
+        parseNumbers,
+        parseBooleans,
+        useFastPath,
+        preventCsvInjection,
+        rfc4180Compliant
+      });
+
+      return {
+        success: true,
+        data: json,
+        stats: {
+          rows: json.length,
+          processingTime: Date.now() - startTime
+        }
+      };
+    } catch (error: any) {
+      reply.code(400);
+      return {
+        success: false,
+        error: error.message,
+        code: 'CSV_CONVERSION_ERROR'
+      };
+    }
+  });
+
+  // JSON to CSV endpoint
+  fastify.post(`${prefix}/json-to-csv`, {
+    schema: {
+      body: {
+        type: 'object',
+        required: ['json'],
+        properties: {
+          json: { type: 'array' },
+          delimiter: { type: 'string', default: delimiter },
+          includeHeaders: { type: 'boolean', default: true }
+        }
+      },
+      response: {
+        200: {
+          type: 'object',
+          properties: {
+            success: { type: 'boolean' },
+            data: { type: 'string' },
+            stats: {
+              type: 'object',
+              properties: {
+                size: { type: 'number' },
+                processingTime: { type: 'number' }
+              }
+            }
+          }
+        }
+      }
+    }
+  }, async (request: any, reply: any) => {
+    const startTime = Date.now();
+    const {
+      json,
+      delimiter: reqDelimiter = delimiter,
+      includeHeaders = true
+    } = request.body;
+
+    try {
+      const csv = await jsonToCsvAsync(json, {
+        delimiter: reqDelimiter,
+        includeHeaders,
+        preventCsvInjection,
+        rfc4180Compliant
+      });
+
+      return {
+        success: true,
+        data: csv,
+        stats: {
+          size: Buffer.byteLength(csv),
+          processingTime: Date.now() - startTime
+        }
+      };
+    } catch (error: any) {
+      reply.code(400);
+      return {
+        success: false,
+        error: error.message,
+        code: 'JSON_CONVERSION_ERROR'
+      };
+    }
+  });
+
+  // Универсальный endpoint для автоматической конвертации
+  fastify.post(`${prefix}/auto`, {
+    schema: {
+      body: {
+        oneOf: [
+          { type: 'string' },  // CSV data
+          { type: 'array' },   // JSON array
+          { type: 'object' }   // JSON object
+        ]
+      },
+      headers: {
+        type: 'object',
+        properties: {
+          'content-type': { 
+            type: 'string',
+            enum: ['application/json', 'text/csv', 'text/plain']
+          },
+          'accept': { 
+            type: 'string',
+            enum: ['application/json', 'text/csv']
+          }
+        }
+      },
+      querystring: {
+        type: 'object',
+        properties: {
+          format: { type: 'string', enum: ['json', 'csv'] },
+          delimiter: { type: 'string' }
+        }
+      }
+    }
+  }, async (request: any, reply: any) => {
+    const startTime = Date.now();
+    const contentType = request.headers['content-type'] || '';
+    const acceptHeader = request.headers['accept'] || 'application/json';
+    const { format, delimiter: queryDelimiter } = request.query;
+    
+    const reqDelimiter = queryDelimiter || delimiter;
+    
+    try {
+      let inputFormat = 'unknown';
+      const outputFormat = format || (acceptHeader.includes('text/csv') ? 'csv' : 'json');
+      
+      // Определяем формат входных данных
+      if (contentType.includes('application/json') || Array.isArray(request.body)) {
+        inputFormat = 'json';
+      } else if (contentType.includes('text/csv') || 
+                contentType.includes('text/plain') ||
+                (typeof request.body === 'string' && request.body.includes(','))) {
+        inputFormat = 'csv';
+      }
+
+      if (inputFormat === 'unknown') {
+        reply.code(400);
+        return {
+          success: false,
+          error: 'Unable to determine input format',
+          code: 'UNKNOWN_FORMAT'
+        };
+      }
+
+      let result: any;
+      const stats: ProcessingStats = {
+        inputSize: 0,
+        outputSize: 0,
+        processingTime: 0,
+        conversion: `${inputFormat}→${outputFormat}`
+      };
+
+      const conversionOptions = {
+        delimiter: reqDelimiter,
+        useFastPath: enableFastPath,
+        preventCsvInjection,
+        rfc4180Compliant
+      };
+
+      if (inputFormat === 'json' && outputFormat === 'csv') {
+        const jsonData = Array.isArray(request.body) ? request.body : [request.body];
+        stats.inputSize = Buffer.byteLength(JSON.stringify(jsonData));
+        
+        result = await jsonToCsvAsync(jsonData, {
+          ...conversionOptions,
+          includeHeaders: true
+        });
+        stats.outputSize = Buffer.byteLength(result);
+        
+        reply.header('Content-Type', 'text/csv; charset=utf-8');
+        
+      } else if (inputFormat === 'csv' && outputFormat === 'json') {
+        const csvData = typeof request.body === 'string' ? request.body : String(request.body);
+        stats.inputSize = Buffer.byteLength(csvData);
+        
+        result = await csvToJsonAsync(csvData, {
+          ...conversionOptions,
+          parseNumbers: true,
+          parseBooleans: true
+        });
+        stats.outputSize = Buffer.byteLength(JSON.stringify(result));
+        
+        reply.header('Content-Type', 'application/json; charset=utf-8');
+        
+      } else {
+        // Нет необходимости в конвертации
+        result = request.body;
+        stats.conversion = 'none';
+        stats.inputSize = Buffer.byteLength(JSON.stringify(result));
+        stats.outputSize = stats.inputSize;
+      }
+
+      stats.processingTime = Date.now() - startTime;
+
+      return {
+        success: true,
+        data: result,
+        format: outputFormat,
+        inputFormat,
+        stats
+      };
+
+    } catch (error: any) {
+      reply.code(400);
+      return {
+        success: false,
+        error: error.message,
+        code: 'CONVERSION_ERROR',
+        details: (process.env as any)['NODE_ENV'] === 'development' ? error.stack : undefined
+      };
+    }
+  });
+
+  // Streaming endpoint для больших файлов
+  fastify.post(`${prefix}/stream`, {
+    schema: {
+      body: {
+        type: 'object',
+        required: ['direction'],
+        properties: {
+          direction: { 
+            type: 'string', 
+            enum: ['csv-to-json', 'json-to-csv'] 
+          },
+          delimiter: { type: 'string', default: delimiter }
+        }
+      }
+    }
+  }, async (request: any, reply: any) => {
+    const { direction, delimiter: reqDelimiter = delimiter } = request.body;
+    
+    if (direction === 'csv-to-json') {
+      reply.header('Content-Type', 'application/x-ndjson');
+      reply.header('Transfer-Encoding', 'chunked');
+      
+      // Здесь будет реализация streaming
+      // Пока возвращаем заглушку
+      reply.send(JSON.stringify({
+        success: false,
+        error: 'Streaming endpoint not implemented yet',
+        code: 'NOT_IMPLEMENTED'
+      }));
+      
+    } else if (direction === 'json-to-csv') {
+      reply.header('Content-Type', 'text/csv');
+      reply.header('Transfer-Encoding', 'chunked');
+      
+      // Здесь будет реализация streaming
+      reply.send('Streaming endpoint not implemented yet\n');
+    }
+  });
+
+  // Декоратор для прямого доступа к функциям конвертации
+  fastify.decorate('jtcsv', {
+    csvToJson: async (csv: string, options: Partial<CsvToJsonOptions> = {}) => {
+      return csvToJsonAsync(csv, {
+        delimiter,
+        useFastPath: enableFastPath,
+        preventCsvInjection,
+        rfc4180Compliant,
+        ...options
+      });
+    },
+    
+    jsonToCsv: async (json: any[], options: Partial<JsonToCsvOptions> = {}) => {
+      return jsonToCsvAsync(json, {
+        delimiter,
+        preventCsvInjection,
+        rfc4180Compliant,
+        ...options
+      });
+    },
+    
+    health: () => ({
+      service: 'jtcsv-fastify-plugin',
+      status: 'healthy',
+      version: '1.0.0'
+    })
+  });
+
+  console.log(`✅ JTCSV Fastify plugin зарегистрирован с префиксом: ${prefix}`);
+}
+
+// Экспортируем как Fastify plugin
+export default fp(jtcsvFastifyPlugin, {
+  fastify: '4.x',
+  name: '@jtcsv/fastify'
+});
+
+// Экспортируем также как обычную функцию
+export { jtcsvFastifyPlugin };

package/plugins/hono/index.ts

@@ -0,0 +1,226 @@
+/**
+ * Hono plugin for jtcsv
+ * Provides middleware and response helpers for CSV processing in Hono applications
+ * @module plugins/hono
+ */
+
+import { csvToJson, jsonToCsv } from '../../index-core';
+import type { CsvToJsonOptions, JsonToCsvOptions } from '../../src/types';
+
+/**
+ * Hono context type (simplified)
+ */
+interface HonoContext {
+  req: {
+    text(): Promise<string>;
+  };
+  set(key: string, value: any): void;
+}
+
+/**
+ * Options for CSV middleware
+ */
+export interface CsvMiddlewareOptions extends CsvToJsonOptions {
+  // Additional options specific to CSV middleware
+}
+
+/**
+ * Options for CSV response
+ */
+export interface CsvResponseOptions extends JsonToCsvOptions {
+  // Additional options specific to CSV response
+}
+
+/**
+ * Normalize filename for CSV download
+ */
+function normalizeFilename(filename?: string): string {
+  if (!filename || typeof filename !== 'string') {
+    return 'export.csv';
+  }
+  return filename.includes('.') ? filename : `${filename}.csv`;
+}
+
+/**
+ * CSV middleware for Hono
+ * Parses incoming CSV request bodies and attaches parsed data to context
+ * 
+ * @example
+ * app.post('/upload', csvMiddleware(), async (c) => {
+ *   const data = c.get('csv');
+ *   return c.json({ success: true, data });
+ * });
+ */
+export function csvMiddleware(options: CsvMiddlewareOptions = {}): any {
+  return async (c: HonoContext, next: () => Promise<void>) => {
+    try {
+      const csvText = await c.req.text();
+      const rows = await csvToJson(csvText, options);
+      c.set('csv', rows);
+      await next();
+    } catch (error) {
+      // Re-throw error for Hono error handling
+      throw error;
+    }
+  };
+}
+
+/**
+ * Async CSV middleware for Hono
+ * Uses async/await for better performance with large files
+ */
+export function asyncCsvMiddleware(options: CsvMiddlewareOptions = {}): any {
+  return async (c: HonoContext, next: () => Promise<void>) => {
+    try {
+      const csvText = await c.req.text();
+      const rows = await csvToJson(csvText, options);
+      c.set('csv', rows);
+      await next();
+    } catch (error) {
+      throw error;
+    }
+  };
+}
+
+/**
+ * Creates a CSV response for Hono
+ * Converts data to CSV and returns appropriate headers
+ * 
+ * @example
+ * app.get('/export', async (c) => {
+ *   const data = await getData();
+ *   const response = createCsvResponse(data, 'export.csv');
+ *   return new Response(response.csv, { headers: response.headers });
+ * });
+ */
+export function createCsvResponse(
+  data: any,
+  filename: string = 'export.csv',
+  options: CsvResponseOptions = {}
+): { csv: string; headers: Record<string, string> } {
+  const safeName = normalizeFilename(filename);
+  const rows = Array.isArray(data) ? data : [data];
+  const csv = jsonToCsv(rows, options);
+
+  return {
+    csv,
+    headers: {
+      'Content-Type': 'text/csv; charset=utf-8',
+      'Content-Disposition': `attachment; filename="${safeName}"`
+    }
+  };
+}
+
+/**
+ * Async version of createCsvResponse
+ * Uses async/await for better performance with large files
+ */
+export async function createAsyncCsvResponse(
+  data: any,
+  filename: string = 'export.csv',
+  options: CsvResponseOptions = {}
+): Promise<{ csv: string; headers: Record<string, string> }> {
+  const safeName = normalizeFilename(filename);
+  const rows = Array.isArray(data) ? data : [data];
+  const csv = await jsonToCsv(rows, options);
+
+  return {
+    csv,
+    headers: {
+      'Content-Type': 'text/csv; charset=utf-8',
+      'Content-Disposition': `attachment; filename="${safeName}"`
+    }
+  };
+}
+
+/**
+ * CSV response helper for Hono
+ * Returns a Response object with CSV data
+ * 
+ * @example
+ * app.get('/export', async (c) => {
+ *   const data = await getData();
+ *   return csvResponse(c, data, 'export.csv');
+ * });
+ */
+export function csvResponse(
+  data: any,
+  filename: string = 'export.csv',
+  options: CsvResponseOptions = {}
+): Response {
+  const { csv, headers } = createCsvResponse(data, filename, options);
+  return new Response(csv, { headers });
+}
+
+/**
+ * Async CSV response helper for Hono
+ * Returns a Response object with CSV data using async processing
+ */
+export async function asyncCsvResponse(
+  data: any,
+  filename: string = 'export.csv',
+  options: CsvResponseOptions = {}
+): Promise<Response> {
+  const { csv, headers } = await createAsyncCsvResponse(data, filename, options);
+  return new Response(csv, { headers });
+}
+
+/**
+ * CSV parsing endpoint helper
+ * Creates a route handler that parses CSV and returns JSON
+ * 
+ * @example
+ * app.post('/parse', csvParseEndpoint());
+ */
+export function csvParseEndpoint(options: CsvMiddlewareOptions = {}): any {
+  return async (c: HonoContext) => {
+    try {
+      const csvText = await c.req.text();
+      const rows = await csvToJson(csvText, options);
+      return new Response(JSON.stringify(rows), {
+        headers: { 'Content-Type': 'application/json' }
+      });
+    } catch (error) {
+      return new Response(
+        JSON.stringify({ error: error instanceof Error ? error.message : 'Unknown error' }),
+        { status: 400, headers: { 'Content-Type': 'application/json' } }
+      );
+    }
+  };
+}
+
+/**
+ * CSV download endpoint helper
+ * Creates a route handler that returns CSV data
+ * 
+ * @example
+ * app.get('/download', csvDownloadEndpoint(async () => await getData()));
+ */
+export function csvDownloadEndpoint(
+  dataProvider: () => Promise<any> | any,
+  filename: string = 'export.csv',
+  options: CsvResponseOptions = {}
+): any {
+  return async (c: HonoContext) => {
+    try {
+      const data = await (typeof dataProvider === 'function' ? dataProvider() : dataProvider);
+      return asyncCsvResponse(data, filename, options);
+    } catch (error) {
+      return new Response(
+        JSON.stringify({ error: error instanceof Error ? error.message : 'Unknown error' }),
+        { status: 500, headers: { 'Content-Type': 'application/json' } }
+      );
+    }
+  };
+}
+
+export default {
+  csvMiddleware,
+  asyncCsvMiddleware,
+  createCsvResponse,
+  createAsyncCsvResponse,
+  csvResponse,
+  asyncCsvResponse,
+  csvParseEndpoint,
+  csvDownloadEndpoint,
+};