CSV Parsing

/**
 * Creates a new CSV parser stream
 * @param args - Parser configuration options
 * @returns CsvParserStream instance for parsing operations
 */
function parse<I extends Row, O extends Row>(args?: ParserOptionsArgs): CsvParserStream<I, O>;

import { parse } from "fast-csv";

// Basic parsing with headers
const parser = parse({ headers: true });
parser.on("data", (row) => console.log(row));
parser.on("end", (rowCount) => console.log(`Parsed ${rowCount} rows`));

// Custom delimiter and options
const tsvParser = parse({
  delimiter: "\t",
  headers: ["name", "age", "city"],
  trim: true
});

/**
 * Parses CSV from a file path
 * @param location - File path to CSV file
 * @param options - Parser configuration options
 * @returns CsvParserStream instance
 */
function parseFile<I extends Row, O extends Row>(
  location: string, 
  options?: ParserOptionsArgs
): CsvParserStream<I, O>;

import { parseFile } from "fast-csv";

// Parse file with headers
parseFile("./data/users.csv", { headers: true })
  .on("data", (row) => {
    console.log(`User: ${row.name}, Age: ${row.age}`);
  })
  .on("end", () => console.log("File parsing complete"));

// Parse with custom options
parseFile("./data/products.csv", {
  headers: ["id", "name", "price"],
  skipRows: 1,
  maxRows: 1000
});

/**
 * Parses CSV from a string
 * @param string - CSV data as string
 * @param options - Parser configuration options
 * @returns CsvParserStream instance
 */
function parseString<I extends Row, O extends Row>(
  string: string, 
  options?: ParserOptionsArgs
): CsvParserStream<I, O>;

import { parseString } from "fast-csv";

const csvData = `name,age,city
John,25,New York
Jane,30,San Francisco`;

parseString(csvData, { headers: true })
  .on("data", (row) => console.log(row))
  .on("end", () => console.log("String parsing complete"));

/**
 * Parses CSV from an existing readable stream
 * @param stream - Readable stream containing CSV data
 * @param options - Parser configuration options
 * @returns CsvParserStream instance
 */
function parseStream<I extends Row, O extends Row>(
  stream: NodeJS.ReadableStream, 
  options?: ParserOptionsArgs
): CsvParserStream<I, O>;

import { parseStream } from "fast-csv";
import fs from "fs";
import { createGunzip } from "zlib";

// Parse from compressed file
const gzipStream = fs.createReadStream("data.csv.gz").pipe(createGunzip());
parseStream(gzipStream, { headers: true })
  .on("data", (row) => console.log(row));

class CsvParserStream<I extends Row, O extends Row> extends Transform {
  /**
   * Adds a transform function to modify parsed rows
   * @param transformFunction - Function to transform each row
   * @returns This stream instance for chaining
   */
  transform(transformFunction: RowTransformFunction<I, O>): CsvParserStream<I, O>;
  
  /**
   * Adds a validation function for parsed rows
   * @param validateFunction - Function to validate each row
   * @returns This stream instance for chaining
   */
  validate(validateFunction: RowValidate<O>): CsvParserStream<I, O>;
}

import { parse } from "fast-csv";

// With transform and validation
parse({ headers: true })
  .transform((row) => ({
    name: row.name.trim().toUpperCase(),
    age: parseInt(row.age),
    email: row.email.toLowerCase()
  }))
  .validate((row) => {
    return row.age >= 0 && row.email.includes("@");
  })
  .on("data", (row) => console.log("Valid row:", row))
  .on("error", (err) => console.error("Validation error:", err));

// Async transform
parse({ headers: true })
  .transform((row, callback) => {
    // Simulate async operation
    setTimeout(() => {
      callback(null, { ...row, processed: true });
    }, 10);
  });

interface ParserOptionsArgs {
  /** Enable object mode for streaming (default: true) */
  objectMode?: boolean;
  
  /** Field delimiter character (default: ',') */
  delimiter?: string;
  
  /** Quote character for escaping fields (default: '"') */
  quote?: string | null;
  
  /** Escape character (default: same as quote) */
  escape?: string;
  
  /** Header handling: true for auto-detect, array for custom headers, function for transform */
  headers?: boolean | HeaderTransformFunction | HeaderArray;
  
  /** Rename headers to safe property names (default: false) */
  renameHeaders?: boolean;
  
  /** Ignore empty rows (default: false) */
  ignoreEmpty?: boolean;
  
  /** Comment character to ignore lines (default: null) */
  comment?: string;
  
  /** Strict column count validation (default: false) */
  strictColumnHandling?: boolean;
  
  /** Discard columns not in headers (default: false) */
  discardUnmappedColumns?: boolean;
  
  /** Trim whitespace from all fields (default: false) */
  trim?: boolean;
  
  /** Trim leading whitespace (default: false) */
  ltrim?: boolean;
  
  /** Trim trailing whitespace (default: false) */
  rtrim?: boolean;
  
  /** Text encoding (default: 'utf8') */
  encoding?: string;
  
  /** Maximum number of rows to parse (default: 0 = unlimited) */
  maxRows?: number;
  
  /** Number of lines to skip at start (default: 0) */
  skipLines?: number;
  
  /** Number of rows to skip after parsing starts (default: 0) */
  skipRows?: number;
}

// Parser-specific row types
type Row<V = any> = RowMap<V> | RowArray<V>;
type RowMap<V = any> = Record<string, V>;
type RowArray<V = any> = V[];

// Validation result interface
interface RowValidationResult<R extends Row> {
  row: R | null;
  isValid: boolean;
  reason?: string;
}

// Transform function types
type RowTransformCallback<R extends Row> = (error?: Error | null, row?: R) => void;
type SyncRowTransform<I extends Row, O extends Row> = (row: I) => O;
type AsyncRowTransform<I extends Row, O extends Row> = (row: I, cb: RowTransformCallback<O>) => void;
type RowTransformFunction<I extends Row, O extends Row> = SyncRowTransform<I, O> | AsyncRowTransform<I, O>;

// Validation function types
type RowValidateCallback = (error?: Error | null, isValid?: boolean, reason?: string) => void;
type SyncRowValidate<R extends Row> = (row: R) => boolean;
type AsyncRowValidate<R extends Row> = (row: R, cb: RowValidateCallback) => void;
type RowValidate<R extends Row> = AsyncRowValidate<R> | SyncRowValidate<R>;
type RowValidatorCallback<R extends Row> = (error: Error | null, result?: RowValidationResult<R>) => void;

// Header handling types
type HeaderArray = (string | undefined | null)[];
type HeaderTransformFunction = (headers: HeaderArray) => HeaderArray;

// Event handling example
parse({ headers: true })
  .on("headers", (headers) => console.log("Headers:", headers))
  .on("data", (row) => console.log("Row:", row))
  .on("end", (rowCount) => console.log(`Total rows: ${rowCount}`))
  .on("error", (error) => console.error("Parse error:", error));