jtcsv 1.1.0

package/index.d.ts

@@ -0,0 +1,348 @@
+declare module 'jtcsv' {
+  import { Readable, Writable, Transform } from 'stream';
+
+  // JSON to CSV interfaces
+  export interface JsonToCsvOptions {
+    /** CSV delimiter (default: ';') */
+    delimiter?: string;
+    /** Include headers row (default: true) */
+    includeHeaders?: boolean;
+    /** Rename column headers { oldKey: newKey } */
+    renameMap?: Record<string, string>;
+    /** Template for guaranteed column order */
+    template?: Record<string, any>;
+    /** Maximum number of records to process (default: 1,000,000) */
+    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;
+  }
+
+  export interface SaveAsCsvOptions extends JsonToCsvOptions {
+    /** Validate file path security (default: true) */
+    validatePath?: boolean;
+  }
+
+  // CSV to JSON interfaces
+  export interface CsvToJsonOptions {
+    /** CSV delimiter (default: ';') */
+    delimiter?: string;
+    /** Whether CSV has headers row (default: true) */
+    hasHeaders?: boolean;
+    /** Map for renaming column headers { newKey: oldKey } */
+    renameMap?: Record<string, string>;
+    /** Trim whitespace from values (default: true) */
+    trim?: boolean;
+    /** Parse numeric values (default: false) */
+    parseNumbers?: boolean;
+    /** Parse boolean values (default: false) */
+    parseBooleans?: boolean;
+    /** Maximum number of rows to process (default: 1,000,000) */
+    maxRows?: number;
+  }
+
+  // JSON save interfaces
+  export interface SaveAsJsonOptions {
+    /** Format JSON with indentation (default: false) */
+    prettyPrint?: boolean;
+    /** Maximum file size in bytes (default: 10MB = 10485760) */
+    maxSize?: number;
+  }
+
+  // Streaming interfaces
+  export interface JsonToCsvStreamOptions extends JsonToCsvOptions {
+    /** Custom transform function for each row */
+    transform?: (row: Record<string, any>) => Record<string, any>;
+    /** JSON schema for validation and formatting */
+    schema?: Record<string, any>;
+    /** Add UTF-8 BOM for Excel compatibility (default: true) */
+    addBOM?: boolean;
+  }
+
+  export interface CsvToJsonStreamOptions extends CsvToJsonOptions {
+    /** Custom transform function for each row */
+    transform?: (row: Record<string, any>) => Record<string, any>;
+    /** JSON schema for validation and formatting */
+    schema?: Record<string, any>;
+  }
+
+  // Error classes
+  export class JtcsvError extends Error {
+    code: string;
+    constructor(message: string, code?: string);
+  }
+
+  export class ValidationError extends JtcsvError {
+    constructor(message: string);
+  }
+
+  export class SecurityError extends JtcsvError {
+    constructor(message: string);
+  }
+
+  export class FileSystemError extends JtcsvError {
+    originalError?: Error;
+    constructor(message: string, originalError?: Error);
+  }
+
+  export class ParsingError extends JtcsvError {
+    lineNumber?: number;
+    column?: number;
+    constructor(message: string, lineNumber?: number, column?: number);
+  }
+
+  export class LimitError extends JtcsvError {
+    limit: number;
+    actual: number;
+    constructor(message: string, limit: number, actual: number);
+  }
+
+  export class ConfigurationError extends JtcsvError {
+    constructor(message: string);
+  }
+
+  // Utility functions
+  export function createErrorMessage(type: string, details: string): string;
+  export function handleError(error: Error, context?: Record<string, any>): void;
+  export function safeExecute<T>(
+    fn: () => Promise<T>,
+    errorType: string,
+    context?: Record<string, any>
+  ): Promise<T>;
+  export function safeExecute<T>(
+    fn: () => T,
+    errorType: string,
+    context?: Record<string, any>
+  ): T;
+
+  /**
+   * Convert JSON array to CSV string
+   * @param data Array of objects to convert
+   * @param options Conversion options
+   * @returns CSV string
+   * @throws {ValidationError} If data is not an array
+   * @throws {LimitError} If record limit exceeded
+   * @throws {ConfigurationError} If options are invalid
+   */
+  export function jsonToCsv<T extends Record<string, any>>(
+    data: T[], 
+    options?: JsonToCsvOptions
+  ): string;
+
+  /**
+   * Preprocess data by unwrapping nested objects and arrays
+   * @param data Input data array
+   * @returns Processed data with flattened structure
+   */
+  export function preprocessData<T extends Record<string, any>>(
+    data: T[]
+  ): Record<string, any>[];
+
+  /**
+   * Save JSON data as CSV file with security validation
+   * @param data Array of objects to convert
+   * @param filePath Output file path (must end with .csv)
+   * @param options Conversion and security options
+   * @returns Promise that resolves when file is saved
+   * @throws {ValidationError} If file path is invalid
+   * @throws {SecurityError} If directory traversal detected
+   * @throws {FileSystemError} If file system operation fails
+   */
+  export function saveAsCsv<T extends Record<string, any>>(
+    data: T[], 
+    filePath: string, 
+    options?: SaveAsCsvOptions
+  ): Promise<void>;
+
+  /**
+   * Deeply unwrap values (internal utility)
+   * @param value Value to unwrap
+   * @param depth Current depth
+   * @param maxDepth Maximum depth (default: 10)
+   * @returns Unwrapped value
+   */
+  export function deepUnwrap(
+    value: any, 
+    depth?: number, 
+    maxDepth?: number
+  ): any;
+
+  /**
+   * Convert CSV string to JSON array
+   * @param csv CSV string to convert
+   * @param options Conversion options
+   * @returns JSON array
+   * @throws {ValidationError} If input is not a string
+   * @throws {ParsingError} If CSV parsing fails
+   * @throws {LimitError} If row limit exceeded
+   */
+  export function csvToJson(
+    csv: string, 
+    options?: CsvToJsonOptions
+  ): Record<string, any>[];
+
+  /**
+   * Read CSV file and convert it to JSON array
+   * @param filePath Path to CSV file
+   * @param options Conversion options
+   * @returns Promise that resolves to JSON array
+   * @throws {ValidationError} If file path is invalid
+   * @throws {SecurityError} If directory traversal detected
+   * @throws {FileSystemError} If file not found or unreadable
+   */
+  export function readCsvAsJson(
+    filePath: string, 
+    options?: CsvToJsonOptions
+  ): Promise<Record<string, any>[]>;
+
+  /**
+   * Synchronously read CSV file and convert it to JSON array
+   * @param filePath Path to CSV file
+   * @param options Conversion options
+   * @returns JSON array
+   * @throws {ValidationError} If file path is invalid
+   * @throws {SecurityError} If directory traversal detected
+   * @throws {FileSystemError} If file not found or unreadable
+   */
+  export function readCsvAsJsonSync(
+    filePath: string, 
+    options?: CsvToJsonOptions
+  ): Record<string, any>[];
+
+  /**
+   * Save data as JSON file with security validation
+   * @param data Data to save as JSON
+   * @param filePath Output file path (must end with .json)
+   * @param options Save options
+   * @returns Promise that resolves when file is saved
+   * @throws {ValidationError} If file path is invalid or data cannot be stringified
+   * @throws {SecurityError} If directory traversal detected
+   * @throws {FileSystemError} If file system operation fails
+   * @throws {LimitError} If file size exceeds limit
+   */
+  export function saveAsJson(
+    data: any, 
+    filePath: string, 
+    options?: SaveAsJsonOptions
+  ): Promise<void>;
+
+  /**
+   * Synchronously save data as JSON file with security validation
+   * @param data Data to save as JSON
+   * @param filePath Output file path (must end with .json)
+   * @param options Save options
+   * @returns Path to saved file
+   * @throws {ValidationError} If file path is invalid or data cannot be stringified
+   * @throws {SecurityError} If directory traversal detected
+   * @throws {FileSystemError} If file system operation fails
+   * @throws {LimitError} If file size exceeds limit
+   */
+  export function saveAsJsonSync(
+    data: any, 
+    filePath: string, 
+    options?: SaveAsJsonOptions
+  ): string;
+
+  /**
+   * Validate file path to prevent path traversal attacks (internal)
+   * @param filePath File path to validate
+   * @returns Validated absolute path
+   * @throws {ValidationError} If path is invalid
+   * @throws {SecurityError} If path traversal detected
+   */
+  export function validateFilePath(filePath: string): string;
+
+  // Streaming JSON to CSV functions
+
+  /**
+   * Creates a transform stream that converts JSON objects to CSV rows
+   * @param options Configuration options
+   * @returns Transform stream
+   */
+  export function createJsonToCsvStream(
+    options?: JsonToCsvStreamOptions
+  ): Transform;
+
+  /**
+   * Converts a readable stream of JSON objects to CSV and writes to a writable stream
+   * @param inputStream Readable stream of JSON objects
+   * @param outputStream Writable stream for CSV output
+   * @param options Configuration options
+   * @returns Promise that resolves when streaming is complete
+   */
+  export function streamJsonToCsv(
+    inputStream: Readable,
+    outputStream: Writable,
+    options?: JsonToCsvStreamOptions
+  ): Promise<void>;
+
+  /**
+   * Converts JSON to CSV and saves it to a file using streaming
+   * @param inputStream Readable stream of JSON objects
+   * @param filePath Path to save the CSV file
+   * @param options Configuration options
+   * @returns Promise that resolves when file is saved
+   */
+  export function saveJsonStreamAsCsv(
+    inputStream: Readable,
+    filePath: string,
+    options?: JsonToCsvStreamOptions
+  ): Promise<void>;
+
+  /**
+   * Creates a readable stream from an array of JSON objects
+   * @param data Array of JSON objects
+   * @returns Readable stream
+   */
+  export function createJsonReadableStream(
+    data: Record<string, any>[]
+  ): Readable;
+
+  /**
+   * Creates a writable stream that collects CSV data
+   * @returns Writable stream that collects data
+   */
+  export function createCsvCollectorStream(): Writable;
+
+  // Streaming CSV to JSON functions
+
+  /**
+   * Creates a transform stream that converts CSV chunks to JSON objects
+   * @param options Configuration options
+   * @returns Transform stream
+   */
+  export function createCsvToJsonStream(
+    options?: CsvToJsonStreamOptions
+  ): Transform;
+
+  /**
+   * Converts a readable stream of CSV text to JSON objects
+   * @param inputStream Readable stream of CSV text
+   * @param outputStream Writable stream for JSON objects
+   * @param options Configuration options
+   * @returns Promise that resolves when streaming is complete
+   */
+  export function streamCsvToJson(
+    inputStream: Readable,
+    outputStream: Writable,
+    options?: CsvToJsonStreamOptions
+  ): Promise<void>;
+
+  /**
+   * Reads CSV file and converts it to JSON using streaming
+   * @param filePath Path to CSV file
+   * @param options Configuration options
+   * @returns Readable stream of JSON objects
+   */
+  export function createCsvFileToJsonStream(
+    filePath: string,
+    options?: CsvToJsonStreamOptions
+  ): Promise<Readable>;
+
+  /**
+   * Creates a writable stream that collects JSON objects into an array
+   * @returns Writable stream that collects data
+   */
+  export function createJsonCollectorStream(): Writable;
+}

package/index.js

@@ -0,0 +1,44 @@
+// Main entry point for the jtcsv module
+// Exports both JSON→CSV and CSV→JSON functions
+
+const jsonToCsvModule = require('./json-to-csv');
+const csvToJsonModule = require('./csv-to-json');
+const errorsModule = require('./errors');
+const jsonSaveModule = require('./json-save');
+const streamJsonToCsvModule = require('./stream-json-to-csv');
+const streamCsvToJsonModule = require('./stream-csv-to-json');
+
+// Combine all exports
+module.exports = {
+  // JSON to CSV functions
+  jsonToCsv: jsonToCsvModule.jsonToCsv,
+  preprocessData: jsonToCsvModule.preprocessData,
+  saveAsCsv: jsonToCsvModule.saveAsCsv,
+  deepUnwrap: jsonToCsvModule.deepUnwrap,
+  validateFilePath: jsonToCsvModule.validateFilePath,
+  
+  // CSV to JSON functions
+  csvToJson: csvToJsonModule.csvToJson,
+  readCsvAsJson: csvToJsonModule.readCsvAsJson,
+  readCsvAsJsonSync: csvToJsonModule.readCsvAsJsonSync,
+
+  // JSON save functions
+  saveAsJson: jsonSaveModule.saveAsJson,
+  saveAsJsonSync: jsonSaveModule.saveAsJsonSync,
+
+  // Streaming JSON to CSV functions
+  createJsonToCsvStream: streamJsonToCsvModule.createJsonToCsvStream,
+  streamJsonToCsv: streamJsonToCsvModule.streamJsonToCsv,
+  saveJsonStreamAsCsv: streamJsonToCsvModule.saveJsonStreamAsCsv,
+  createJsonReadableStream: streamJsonToCsvModule.createJsonReadableStream,
+  createCsvCollectorStream: streamJsonToCsvModule.createCsvCollectorStream,
+
+  // Streaming CSV to JSON functions
+  createCsvToJsonStream: streamCsvToJsonModule.createCsvToJsonStream,
+  streamCsvToJson: streamCsvToJsonModule.streamCsvToJson,
+  createCsvFileToJsonStream: streamCsvToJsonModule.createCsvFileToJsonStream,
+  createJsonCollectorStream: streamCsvToJsonModule.createJsonCollectorStream,
+
+  // Error classes
+  ...errorsModule
+};

package/json-save.js

@@ -0,0 +1,248 @@
+/**
+ * JSON Save Module - Node.js Module
+ * 
+ * A lightweight module for saving JSON data to files with security validation.
+ * 
+ * @module json-save
+ */
+
+const {
+  ValidationError,
+  SecurityError,
+  FileSystemError,
+  LimitError,
+  ConfigurationError,
+  safeExecute
+} = require('./errors');
+
+/**
+ * Validates file path for JSON saving
+ * @private
+ */
+function validateJsonFilePath(filePath) {
+  const path = require('path');
+  
+  // Basic validation
+  if (typeof filePath !== 'string' || filePath.trim() === '') {
+    throw new ValidationError('File path must be a non-empty string');
+  }
+  
+  // Ensure file has .json extension
+  if (!filePath.toLowerCase().endsWith('.json')) {
+    throw new ValidationError('File must have .json extension');
+  }
+  
+  // Get absolute path and check for traversal
+  const absolutePath = path.resolve(filePath);
+  const normalizedPath = path.normalize(filePath);
+  
+  // Prevent directory traversal attacks
+  if (normalizedPath.includes('..') || 
+      /\\\.\.\\|\/\.\.\//.test(filePath) ||
+      filePath.startsWith('..') ||
+      filePath.includes('/..')) {
+    throw new SecurityError('Directory traversal detected in file path');
+  }
+  
+  return absolutePath;
+}
+
+/**
+ * Validates JSON data and options
+ * @private
+ */
+function validateJsonData(data, options) {
+  // Validate data
+  if (data === undefined || data === null) {
+    throw new ValidationError('Data cannot be null or undefined');
+  }
+  
+  // Validate options
+  if (options && typeof options !== 'object') {
+    throw new ConfigurationError('Options must be an object');
+  }
+  
+  // Validate prettyPrint
+  if (options?.prettyPrint !== undefined && typeof options.prettyPrint !== 'boolean') {
+    throw new ConfigurationError('prettyPrint must be a boolean');
+  }
+  
+  // Validate maxSize
+  if (options?.maxSize && (typeof options.maxSize !== 'number' || options.maxSize <= 0)) {
+    throw new ConfigurationError('maxSize must be a positive number');
+  }
+  
+  return true;
+}
+
+/**
+ * Saves JSON data to a file
+ * 
+ * @param {*} data - Data to save as JSON
+ * @param {string} filePath - Path to save the JSON file
+ * @param {Object} [options] - Configuration options
+ * @param {boolean} [options.prettyPrint=false] - Format JSON with indentation
+ * @param {number} [options.maxSize=10485760] - Maximum file size in bytes (default: 10MB)
+ * @returns {Promise<void>}
+ * 
+ * @example
+ * const { saveAsJson } = require('./json-save');
+ * 
+ * const data = [{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }];
+ * await saveAsJson(data, './output.json', { prettyPrint: true });
+ */
+async function saveAsJson(data, filePath, options = {}) {
+  return safeExecute(async () => {
+    const fs = require('fs').promises;
+    
+    // Validate file path
+    const safePath = validateJsonFilePath(filePath);
+    
+    // Validate data and options
+    validateJsonData(data, options);
+    
+    const opts = options && typeof options === 'object' ? options : {};
+    const {
+      prettyPrint = false,
+      maxSize = 10485760 // 10MB default limit
+    } = opts;
+    
+    // Convert data to JSON string
+    let jsonString;
+    try {
+      if (prettyPrint) {
+        jsonString = JSON.stringify(data, null, 2);
+      } else {
+        jsonString = JSON.stringify(data);
+      }
+    } catch (error) {
+      if (error.message.includes('circular') || error.message.includes('Converting circular')) {
+        throw new ValidationError('Data contains circular references');
+      }
+      throw new ValidationError(`Failed to stringify JSON: ${error.message}`);
+    }
+    
+    // Check size limit
+    const byteSize = Buffer.byteLength(jsonString, 'utf8');
+    if (byteSize > maxSize) {
+      throw new LimitError(
+        `JSON size exceeds maximum limit of ${maxSize} bytes`,
+        maxSize,
+        byteSize
+      );
+    }
+    
+    // Ensure directory exists
+    const dir = require('path').dirname(safePath);
+    
+    try {
+      await fs.mkdir(dir, { recursive: true });
+      
+      // Write file
+      await fs.writeFile(safePath, jsonString, 'utf8');
+      
+      return safePath;
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        throw new FileSystemError(`Directory does not exist: ${dir}`, error);
+      }
+      if (error.code === 'EACCES') {
+        throw new FileSystemError(`Permission denied: ${safePath}`, error);
+      }
+      if (error.code === 'ENOSPC') {
+        throw new FileSystemError(`No space left on device: ${safePath}`, error);
+      }
+      
+      throw new FileSystemError(`Failed to write JSON file: ${error.message}`, error);
+    }
+  }, 'FILE_SYSTEM_ERROR', { function: 'saveAsJson' });
+}
+
+/**
+ * Synchronously saves JSON data to a file
+ * 
+ * @param {*} data - Data to save as JSON
+ * @param {string} filePath - Path to save the JSON file
+ * @param {Object} [options] - Configuration options (same as saveAsJson)
+ * @returns {string} Path to saved file
+ */
+function saveAsJsonSync(data, filePath, options = {}) {
+  return safeExecute(() => {
+    const fs = require('fs');
+    
+    // Validate file path
+    const safePath = validateJsonFilePath(filePath);
+    
+    // Validate data and options
+    validateJsonData(data, options);
+    
+    const opts = options && typeof options === 'object' ? options : {};
+    const {
+      prettyPrint = false,
+      maxSize = 10485760 // 10MB default limit
+    } = opts;
+    
+    // Convert data to JSON string
+    let jsonString;
+    try {
+      if (prettyPrint) {
+        jsonString = JSON.stringify(data, null, 2);
+      } else {
+        jsonString = JSON.stringify(data);
+      }
+    } catch (error) {
+      if (error.message.includes('circular') || error.message.includes('Converting circular')) {
+        throw new ValidationError('Data contains circular references');
+      }
+      throw new ValidationError(`Failed to stringify JSON: ${error.message}`);
+    }
+    
+    // Check size limit
+    const byteSize = Buffer.byteLength(jsonString, 'utf8');
+    if (byteSize > maxSize) {
+      throw new LimitError(
+        `JSON size exceeds maximum limit of ${maxSize} bytes`,
+        maxSize,
+        byteSize
+      );
+    }
+    
+    // Ensure directory exists
+    const dir = require('path').dirname(safePath);
+    
+    try {
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+      
+      // Write file
+      fs.writeFileSync(safePath, jsonString, 'utf8');
+      
+      return safePath;
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        throw new FileSystemError(`Directory does not exist: ${dir}`, error);
+      }
+      if (error.code === 'EACCES') {
+        throw new FileSystemError(`Permission denied: ${safePath}`, error);
+      }
+      if (error.code === 'ENOSPC') {
+        throw new FileSystemError(`No space left on device: ${safePath}`, error);
+      }
+      
+      throw new FileSystemError(`Failed to write JSON file: ${error.message}`, error);
+    }
+  }, 'FILE_SYSTEM_ERROR', { function: 'saveAsJsonSync' });
+}
+
+// Export the functions
+module.exports = {
+  saveAsJson,
+  saveAsJsonSync,
+  validateJsonFilePath
+};
+
+// For ES6 module compatibility
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports.default = saveAsJson;
+}