@maximai/maxim-js/src/lib/utils/csvParser.d.ts

Maxim AI JS SDK. Visit https://getmaxim.ai for more info.

/**
 * Configuration options for parsing CSV files.
 *
 * @property delimiter - Character used to separate fields in the CSV
 * @property hasHeader - Whether the first row contains column headers
 * @property quoteChar - Character used to quote fields containing special characters
 * @property escapeChar - Character used to escape quote characters within quoted fields
 * @example
 * // Default CSV parsing
 * const options: CSVParseOptions = {
 *   delimiter: ",",
 *   hasHeader: true,
 *   quoteChar: '"',
 *   escapeChar: '"'
 * };
 *
 * @example
 * // Tab-separated values without headers
 * const tsvOptions: CSVParseOptions = {
 *   delimiter: "\t",
 *   hasHeader: false,
 *   quoteChar: "'",
 *   escapeChar: "\\"
 * };
 */
export type CSVParseOptions = {
    delimiter?: string;
    hasHeader?: boolean;
    quoteChar?: string;
    escapeChar?: string;
};
/**
 * Configuration options for writing CSV files.
 *
 * @property delimiter - Character used to separate fields
 * @property includeHeader - Whether to include column headers in the output
 * @property quoteChar - Character used to quote fields containing special characters
 * @property escapeChar - Character used to escape quote characters within quoted fields
 */
export type CSVWriteOptions = {
    delimiter?: string;
    includeHeader?: boolean;
    quoteChar?: string;
    escapeChar?: string;
};
/**
 * Type representing the structure of columns in a CSV file.
 * Maps column names to their zero-based index positions.
 *
 * @example
 * const structure: ColumnStructure = {
 *   "firstName": 0,
 *   "lastName": 1,
 *   "email": 2,
 *   "age": 3
 * };
 */
export type ColumnStructure = Record<string, number>;
/**
 * Represents a CSV file with optional type information for its columns.
 *
 * Provides methods for reading, parsing, and manipulating CSV data with
 * optional type safety through column structure definitions. Supports
 * both streaming and batch operations for efficient processing of large files.
 *
 * @template T - Optional column structure type for typed access
 * @class CSVFile
 * @example
 * // Basic usage without column structure
 * const csvFile = new CSVFile("data.csv");
 * const rowCount = await csvFile.getRowCount();
 * const firstRow = await csvFile.getRow(0);
 *
 * @example
 * // With typed column structure
 * const typedCSV = new CSVFile("users.csv", {
 *   name: 0,
 *   email: 1,
 *   age: 2
 * });
 *
 * const user = await typedCSV.getRow(0);
 * console.log(user.name, user.email, user.age); // Type-safe access
 *
 * @example
 * // Filtering and mapping
 * const adults = await csvFile.filter(row => parseInt(row.age) >= 18);
 * const names = await csvFile.map(row => row.name.toUpperCase());
 *
 * @example
 * // Writing data to CSV
 * await CSVFile.writeToFile(
 *   [{ name: "John", email: "john@example.com" }],
 *   "output.csv",
 *   { name: 0, email: 1 }
 * );
 */
export declare class CSVFile<T extends ColumnStructure | undefined = undefined> {
    private filePath;
    private options;
    private headerRow;
    private rowCount;
    private columnCount;
    private columnStructure;
    private fileStats;
    /**
     * Creates a new CSVFile instance.
     *
     * @param filePath - The path to the CSV file
     * @param columnStructure - Optional column structure mapping column names to indices
     * @param options - Optional parsing configuration
     * @throws {Error} When column structure is provided but doesn't match the file headers
     * @example
     * // Simple CSV file
     * const csv = new CSVFile("data.csv");
     *
     * @example
     * // With column structure for type safety
     * const csv = new CSVFile("users.csv", {
     *   id: 0,
     *   name: 1,
     *   email: 2
     * });
     *
     * @example
     * // With custom parsing options
     * const csv = new CSVFile("data.tsv", undefined, {
     *   delimiter: "\t",
     *   hasHeader: false,
     *   quoteChar: "'"
     * });
     */
    constructor(filePath: string, columnStructure?: T, options?: CSVParseOptions);
    /**
     * Validates the headers of the CSV file against the provided column structure.
     *
     * @private
     * @async
     * @returns
     * @throws {Error} When headers don't match the column structure
     */
    private validateHeaders;
    /**
     * Parses a single row of the CSV file, handling quotes and escaping.
     *
     * @private
     * @param row - The raw row string to parse
     * @returns Array of parsed field values
     */
    private parseRow;
    /**
     * Gets the total number of rows in the CSV file.
     *
     * @async
     * @returns The total number of rows (excluding header if present)
     * @example
     * const csv = new CSVFile("large-dataset.csv");
     * const totalRows = await csv.getRowCount();
     * console.log(`Dataset contains ${totalRows} records`);
     */
    getRowCount(): Promise<number>;
    /**
     * Gets the number of columns in the CSV file.
     *
     * @async
     * @returns The number of columns
     * @throws {Error} When unable to read the header row
     * @example
     * const columnCount = await csv.getColumnCount();
     * console.log(`CSV has ${columnCount} columns`);
     */
    getColumnCount(): Promise<number>;
    /**
     * Gets the header row of the CSV file.
     *
     * @async
     * @returns Array of header field names, or null if no header
     * @throws {Error} When unable to read the header row
     * @example
     * const headers = await csv.getHeader();
     * console.log("Columns:", headers); // ["name", "email", "age"]
     */
    getHeader(): Promise<string[] | null>;
    /**
     * Gets a specific row from the CSV file.
     * @param index The zero-based index of the row to retrieve.
     * @returns A promise that resolves to the row data, either as an object (if column structure is provided) or as an array of strings.
     * @throws {Error} if the row index is out of bounds.
     * @example
     * const row = await csvFile.getRow(0);
     * console.log(row);
     * // { column1: "value1", column2: "value2" } (if column structure is provided)
     * // OR
     * // ["value1", "value2"] (if column structure is not provided)
     */
    getRow(index: number): Promise<(T extends ColumnStructure ? {
        [K in keyof T]: string;
    } : string[]) | null>;
    /**
     * Creates a typed row object based on the column structure.
     * @private
     * @param row The raw row data as an array of strings.
     * @returns A typed row object if column structure is provided, otherwise the original array.
     */
    private createTypedRow;
    /**
     * Filters rows of the CSV file based on a predicate function.
     * @param predicate A function that takes a row and returns true if the row should be included in the result.
     * @returns A promise that resolves to an array of filtered rows.
     */
    filter(predicate: (row: T extends ColumnStructure ? {
        [K in keyof T]: string;
    } : string[]) => boolean): Promise<(T extends ColumnStructure ? {
        [K in keyof T]: string;
    } : string[])[]>;
    /**
     * Maps each row of the CSV file using a mapper function.
     * @param mapper A function that takes a row and returns a transformed value.
     * @returns A promise that resolves to an array of mapped values.
     */
    map<U>(mapper: (row: T extends ColumnStructure ? {
        [K in keyof T]: string;
    } : string[]) => U): Promise<U[]>;
    /**
     * Processes the CSV file row by row.
     * @private
     * @param rowProcessor A function to process each row.
     * @returns A promise that resolves when all rows have been processed.
     */
    private processFile;
    /**
     * Restructures a CSVFile object with a new column structure.
     * @param csvFile The original CSVFile object.
     * @param newColumnStructure The new column structure to apply.
     * @returns A new CSVFile object with the updated column structure.
     * @throws {Error} if the new column structure doesn't match the CSV file headers.
     */
    static restructure<U extends ColumnStructure>(csvFile: CSVFile<ColumnStructure | undefined>, newColumnStructure: U): Promise<CSVFile<U>>;
    /**
     * Writes data to a CSV file.
     * @param data The data to write, either as an array of objects or an array of arrays.
     * @param outputPath The path where the CSV file should be written.
     * @param columnStructure Optional column structure for typed data.
     * @param options Optional writing options.
     * @returns A promise that resolves when the file has been written.
     * @example
     * const data = [
     *     { column1: "value1", column2: "value2" },
     *     { column1: "value3", column2: "value4" },
     * ];
     * await CSVFile.writeToFile(
     *     data,
     *     "path/to/output.csv",
     *     { column1: 0, column2: 1 }
     * );
     */
    static writeToFile<T extends ColumnStructure | undefined = undefined>(data: (T extends ColumnStructure ? {
        [K in keyof T]: string;
    } : string[])[], outputPath: string, columnStructure?: T, options?: CSVWriteOptions): Promise<void>;
    /**
     * Formats a row of data for CSV output.
     * @private
     * @param row The row data as an array of strings.
     * @param options The CSV writing options.
     * @returns A formatted string representing the CSV row.
     */
    private static formatRow;
}