jtcsv 2.2.7 → 3.0.0

package/examples/cli-tool.ts

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+
+// jtcsv CLI Tool
+// Usage: node cli-tool.js input.json output.csv [options]
+// Example: node cli-tool.js data.json output.csv --delimiter=,
+
+import fs from "fs";
+import path from "path";
+const {  jsonToCsv, saveAsCsv  } = await import("../index.js");
+
+// Parse command line arguments
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const result = {
+    input: null,
+    output: null,
+    delimiter: ';',
+    noHeaders: false,
+    help: false,
+    version: false
+  };
+  
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    
+    if (arg.startsWith('--')) {
+      const [key, value] = arg.slice(2).split('=');
+      
+      switch (key) {
+      case 'delimiter':
+        result.delimiter = value || ',';
+        break;
+      case 'no-headers':
+        result.noHeaders = true;
+        break;
+      case 'help':
+        result.help = true;
+        break;
+      case 'version':
+        result.version = true;
+        break;
+      default:
+        console.warn(`Warning: Unknown option --${key}`);
+      }
+    } else if (!result.input) {
+      result.input = arg;
+    } else if (!result.output) {
+      result.output = arg;
+    }
+  }
+  
+  return result;
+}
+
+// Show help
+function showHelp() {
+  console.log(`
+jtcsv CLI Tool - Convert JSON files to CSV
+`);
+  console.log('Usage:');
+  console.log('  node cli-tool.js <input.json> [output.csv] [options]');
+  console.log('  node cli-tool.js --help');
+  console.log('  node cli-tool.js --version');
+  console.log('');
+  console.log('Arguments:');
+  console.log('  input.json          Input JSON file (required)');
+  console.log('  output.csv          Output CSV file (optional, prints to stdout if not provided)');
+  console.log('');
+  console.log('Options:');
+  console.log('  --delimiter=<char>  CSV delimiter (default: ;)');
+  console.log('  --no-headers        Do not include headers in output');
+  console.log('  --help              Show this help message');
+  console.log('  --version           Show version');
+  console.log('');
+  console.log('Examples:');
+  console.log('  # Convert data.json to data.csv with comma delimiter');
+  console.log('  node cli-tool.js data.json data.csv --delimiter=,');
+  console.log('');
+  console.log('  # Convert and print to console');
+  console.log('  node cli-tool.js data.json');
+  console.log('');
+  console.log('  # Convert without headers');
+  console.log('  node cli-tool.js data.json output.csv --no-headers');
+}
+
+// Show version
+function showVersion() {
+  import packageJson from "../package.json";
+  console.log(`jtcsv CLI Tool v${packageJson.version}`);
+}
+
+// Read JSON file
+function readJsonFile(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    return JSON.parse(content);
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new Error(`File not found: ${filePath}`);
+    } else if (error instanceof SyntaxError) {
+      throw new Error(`Invalid JSON in file: ${filePath}`);
+    }
+    throw error;
+  }
+}
+
+// Main function
+async function main() {
+  const args = parseArgs();
+  
+  if (args.help) {
+    showHelp();
+    return;
+  }
+  
+  if (args.version) {
+    showVersion();
+    return;
+  }
+  
+  if (!args.input) {
+    console.error('Error: Input file is required');
+    showHelp();
+    process.exit(1);
+  }
+  
+  try {
+    // Read and validate input
+    console.log(`Reading ${args.input}...`);
+    const data = readJsonFile(args.input);
+    
+    if (!Array.isArray(data)) {
+      throw new Error('JSON data must be an array of objects');
+    }
+    
+    console.log(`Found ${data.length} records`);
+    
+    // Convert to CSV
+    const options = {
+      delimiter: args.delimiter,
+      includeHeaders: !args.noHeaders
+    };
+    
+    if (args.output) {
+      // Save to file
+      console.log(`Converting to CSV with delimiter '${args.delimiter}'...`);
+      
+      // Using saveAsCsv for better security
+      await saveAsCsv(data, args.output, options);
+      
+      const stats = fs.statSync(args.output);
+      console.log(`✅ Successfully saved to ${args.output}`);
+      console.log(`   File size: ${(stats.size / 1024).toFixed(2)} KB`);
+      console.log(`   Records: ${data.length}`);
+    } else {
+      // Print to stdout
+      const csv = jsonToCsv(data, options);
+      console.log(csv);
+    }
+    
+  } catch (error) {
+    console.error(`❌ Error: ${error.message}`);
+    
+    if (error.message.includes('Directory traversal')) {
+      console.error('   Security violation: Attempted directory traversal');
+    }
+    
+    process.exit(1);
+  }
+}
+
+// Handle uncaught errors
+process.on('uncaughtException', (error) => {
+  console.error('Uncaught error:', error.message);
+  process.exit(1);
+});
+
+// Run if called directly
+if (require.main === module) {
+  main();
+}
+
+export default { parseArgs, readJsonFile, showHelp, showVersion };

package/examples/error-handling.js

@@ -94,13 +94,27 @@ async function comprehensiveErrorHandling() {
 }
 
 function getErrorTypeName(error) {
-  if (error instanceof ValidationError) return 'ValidationError';
-  if (error instanceof SecurityError) return 'SecurityError';
-  if (error instanceof ParsingError) return 'ParsingError';
-  if (error instanceof FileSystemError) return 'FileSystemError';
-  if (error instanceof LimitError) return 'LimitError';
-  if (error instanceof ConfigurationError) return 'ConfigurationError';
-  if (error instanceof JtcsvError) return 'JtcsvError';
+  if (error instanceof ValidationError) {
+    return 'ValidationError';
+  }
+  if (error instanceof SecurityError) {
+    return 'SecurityError';
+  }
+  if (error instanceof ParsingError) {
+    return 'ParsingError';
+  }
+  if (error instanceof FileSystemError) {
+    return 'FileSystemError';
+  }
+  if (error instanceof LimitError) {
+    return 'LimitError';
+  }
+  if (error instanceof ConfigurationError) {
+    return 'ConfigurationError';
+  }
+  if (error instanceof JtcsvError) {
+    return 'JtcsvError';
+  }
   return 'UnknownError';
 }
 

package/examples/error-handling.ts

@@ -0,0 +1,356 @@
+/**
+ * Error Handling Examples for jtcsv
+ *
+ * This file demonstrates proper error handling patterns
+ * using jtcsv's typed error classes.
+ */
+
+import {
+  csvToJson,
+  jsonToCsv,
+  saveAsCsv,
+  readCsvAsJson,
+  // Error classes
+  JtcsvError,
+  ValidationError,
+  SecurityError,
+  ParsingError,
+  FileSystemError,
+  LimitError,
+  ConfigurationError,
+  CsvToJsonOptions,
+  JsonToCsvOptions,
+  SaveAsCsvOptions
+} from 'jtcsv';
+
+// =============================================================================
+// Example 1: Basic Error Handling
+// =============================================================================
+
+function basicErrorHandling(): void {
+  console.log('\n=== Basic Error Handling ===\n');
+
+  // Invalid input type
+  try {
+    csvToJson(null as any);
+  } catch (error: unknown) {
+    if (error instanceof ValidationError) {
+      console.log('ValidationError caught:', error.message);
+      console.log('Error code:', error.code);
+    }
+  }
+
+  // Malformed CSV
+  const malformedCsv = 'name,age\n"unclosed quote,25';
+  try {
+    csvToJson(malformedCsv);
+  } catch (error: unknown) {
+    if (error instanceof ParsingError) {
+      console.log('ParsingError caught:', error.message);
+      console.log('Line number:', (error as any).lineNumber);
+    }
+  }
+}
+
+// =============================================================================
+// Example 2: Comprehensive Error Handling with Type Checks
+// =============================================================================
+
+async function comprehensiveErrorHandling(): Promise<void> {
+  console.log('\n=== Comprehensive Error Handling ===\n');
+
+  const operations = [
+    {
+      name: 'Parse invalid CSV',
+      action: () => csvToJson(12345 as any) // Not a string
+    },
+    {
+      name: 'Convert non-array to CSV',
+      action: () => jsonToCsv('not an array' as any)
+    },
+    {
+      name: 'Read non-existent file',
+      action: async () => await readCsvAsJson('./non-existent-file.csv')
+    },
+    {
+      name: 'Exceed row limit',
+      action: () => {
+        const csv = 'a,b\n' + '1,2\n'.repeat(100);
+        return csvToJson(csv, { maxRows: 5 });
+      }
+    },
+    {
+      name: 'Path traversal attempt',
+      action: async () => await saveAsCsv([], '../../../etc/passwd.csv')
+    }
+  ];
+
+  for (const op of operations) {
+    try {
+      await op.action();
+      console.log(`${op.name}: Success (unexpected)`);
+    } catch (error) {
+      const errorType = getErrorTypeName(error as Error);
+      console.log(`${op.name}: ${errorType} - ${(error as Error).message}`);
+    }
+  }
+}
+
+function getErrorTypeName(error: Error): string {
+  if (error instanceof ValidationError) {
+    return 'ValidationError';
+  }
+  if (error instanceof SecurityError) {
+    return 'SecurityError';
+  }
+  if (error instanceof ParsingError) {
+    return 'ParsingError';
+  }
+  if (error instanceof FileSystemError) {
+    return 'FileSystemError';
+  }
+  if (error instanceof LimitError) {
+    return 'LimitError';
+  }
+  if (error instanceof ConfigurationError) {
+    return 'ConfigurationError';
+  }
+  if (error instanceof JtcsvError) {
+    return 'JtcsvError';
+  }
+  return 'UnknownError';
+}
+
+// =============================================================================
+// Example 3: Error Recovery Strategies
+// =============================================================================
+
+function errorRecoveryStrategies(): void {
+  console.log('\n=== Error Recovery Strategies ===\n');
+
+  // Strategy 1: Fallback to default delimiter
+  function parseWithFallback(csv: string): any[] {
+    const delimiters = [',', ';', '\t', '|'];
+
+    for (const delimiter of delimiters) {
+      try {
+        const result = csvToJson(csv, {
+          delimiter,
+          autoDetect: false
+        });
+        console.log(`Successfully parsed with delimiter: "${delimiter}"`);
+        return result;
+      } catch (error) {
+        console.log(`Failed with delimiter "${delimiter}": ${(error as Error).message}`);
+      }
+    }
+    throw new Error('Could not parse CSV with any known delimiter');
+  }
+
+  const testCsv = 'name|age|city\nJohn|25|NYC\nJane|30|LA';
+  const result = parseWithFallback(testCsv);
+  console.log('Result:', result);
+}
+
+// =============================================================================
+// Example 4: Batch Processing with Error Collection
+// =============================================================================
+
+async function batchProcessingWithErrorCollection(): Promise<void> {
+  console.log('\n=== Batch Processing with Error Collection ===\n');
+
+  const csvFiles = [
+    { name: 'valid.csv', content: 'a,b\n1,2\n3,4' },
+    { name: 'invalid.csv', content: 'a,b\n"unclosed' },
+    { name: 'empty.csv', content: '' },
+    { name: 'valid2.csv', content: 'x,y\n5,6' }
+  ];
+
+  const results = {
+    successful: [] as Array<{ name: string; rowCount: number }>,
+    failed: [] as Array<{ name: string; error: string; errorType: string }>
+  };
+
+  for (const file of csvFiles) {
+    try {
+      const data = csvToJson(file.content);
+      results.successful.push({
+        name: file.name,
+        rowCount: data.length
+      });
+    } catch (error) {
+      results.failed.push({
+        name: file.name,
+        error: (error as Error).message,
+        errorType: getErrorTypeName(error as Error)
+      });
+    }
+  }
+
+  console.log('Processing Results:');
+  console.log('Successful:', results.successful);
+  console.log('Failed:', results.failed);
+  console.log(`\nSuccess rate: ${results.successful.length}/${csvFiles.length}`);
+}
+
+// =============================================================================
+// Example 5: Custom Error Handler Wrapper
+// =============================================================================
+
+interface SafeParserOptions {
+  onError?: (error: Error) => void;
+  defaultValue?: any[];
+}
+
+interface SafeParseResult {
+  success: boolean;
+  data: any[];
+  error: {
+    type: string;
+    message: string;
+    code?: string;
+  } | null;
+}
+
+function createSafeParser(options: SafeParserOptions = {}) {
+  const { onError, defaultValue = [] } = options;
+
+  return function safeParse(csv: string, parseOptions: CsvToJsonOptions = {}): SafeParseResult {
+    try {
+      return {
+        success: true,
+        data: csvToJson(csv, parseOptions),
+        error: null
+      };
+    } catch (error) {
+      if (onError) {
+        onError(error as Error);
+      }
+      return {
+        success: false,
+        data: defaultValue,
+        error: {
+          type: getErrorTypeName(error as Error),
+          message: (error as Error).message,
+          code: (error as any).code
+        }
+      };
+    }
+  };
+}
+
+function customErrorHandlerDemo(): void {
+  console.log('\n=== Custom Error Handler ===\n');
+
+  const safeParse = createSafeParser({
+    onError: (error: Error) => {
+      console.log(`[Logger] Error occurred: ${error.message}`);
+    },
+    defaultValue: []
+  });
+
+  // Test with valid CSV
+  const result1 = safeParse('a,b\n1,2');
+  console.log('Valid CSV result:', result1);
+
+  // Test with invalid CSV
+  const result2 = safeParse(null as any);
+  console.log('Invalid CSV result:', result2);
+}
+
+// =============================================================================
+// Example 6: Async Error Handling with Retries
+// =============================================================================
+
+async function asyncWithRetries(): Promise<void> {
+  console.log('\n=== Async Error Handling with Retries ===\n');
+
+  async function readWithRetry(filePath: string, maxRetries = 3): Promise<any[]> {
+    let lastError: Error | undefined;
+
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        console.log(`Attempt ${attempt}: Reading ${filePath}`);
+        const data = await readCsvAsJson(filePath);
+        return data;
+      } catch (error) {
+        lastError = error as Error;
+        console.log(`Attempt ${attempt} failed: ${(error as Error).message}`);
+
+        if (error instanceof FileSystemError) {
+          // File system errors might be transient
+          await new Promise(r => setTimeout(r, 100 * attempt));
+        } else if (error instanceof ValidationError) {
+          // Validation errors won't resolve with retry
+          throw error;
+        } else if (error instanceof SecurityError) {
+          // Security errors should not be retried
+          throw error;
+        }
+      }
+    }
+
+    throw lastError;
+  }
+
+  try {
+    await readWithRetry('./test-data.csv');
+  } catch (error) {
+    console.log(`All retries failed: ${(error as Error).message}`);
+  }
+}
+
+// =============================================================================
+// Example 7: Schema Validation Error Details
+// =============================================================================
+
+function schemaValidationErrors(): void {
+  console.log('\n=== Schema Validation Errors ===\n');
+
+  const schema = {
+    type: 'object',
+    required: ['name', 'age'],
+    properties: {
+      name: { type: 'string', minLength: 1 },
+      age: { type: 'number', minimum: 0, maximum: 150 }
+    }
+  };
+
+  const data = [
+    { name: 'John', age: 25 },
+    { name: '', age: 30 },          // Invalid: empty name
+    { name: 'Jane', age: -5 },      // Invalid: negative age
+    { name: 'Bob', age: 200 }       // Invalid: age > 150
+  ];
+
+  try {
+    jsonToCsv(data, { schema });
+  } catch (error: unknown) {
+    if (error instanceof ValidationError) {
+      console.log('Schema validation failed:');
+      console.log('Message:', error.message);
+    }
+  }
+}
+
+// =============================================================================
+// Run All Examples
+// =============================================================================
+
+async function main(): Promise<void> {
+  console.log('jtcsv Error Handling Examples\n');
+  console.log('='.repeat(60));
+
+  basicErrorHandling();
+  await comprehensiveErrorHandling();
+  errorRecoveryStrategies();
+  await batchProcessingWithErrorCollection();
+  customErrorHandlerDemo();
+  await asyncWithRetries();
+  schemaValidationErrors();
+
+  console.log('\n' + '='.repeat(60));
+  console.log('All examples completed.');
+}
+
+main().catch(console.error);

package/examples/express-api.js

@@ -162,6 +162,3 @@ app.listen(PORT, () => {
 });
 
 module.exports = app;
-
-
-