csv-stream-lite 0.1.0

package/dist/parser.js

@@ -0,0 +1,596 @@
+import { ByteBuffer } from './byte-buffer.js';
+import { DEFAULT_CHUNK_SIZE } from './defaults.js';
+import { TooFewColumnsError, TooManyColumnsError } from './errors.js';
+import { CsvStringify } from './stringify.js';
+import { bytesToString } from './utils.js';
+const UTF_8_BOM = [0xef, 0xbb, 0xbf];
+/**
+ * Map of character names to their byte values for CSV parsing.
+ * Contains commonly used characters in CSV syntax.
+ */
+const BYTE_MAP = {
+    quotes: 34,
+    comma: 44,
+    backslash: 92,
+    space: 32,
+    tab: 9,
+    carriageReturn: 13,
+    lineFeed: 10,
+};
+const isLineEnd = (byte) => {
+    return byte === BYTE_MAP.lineFeed || byte === BYTE_MAP.carriageReturn;
+};
+/**
+ * Abstract base class for CSV entities that supports both synchronous and asynchronous parsing.
+ * Provides common functionality for reading and streaming CSV data.
+ *
+ * @typeParam T - The type returned by read operations
+ * @typeParam S - The type yielded by stream operations (defaults to T)
+ */
+export class CsvEntity {
+    byteBuffer;
+    separator = ',';
+    escapeChar = '"';
+    consumed = false;
+    /**
+     * Creates a new CSV entity.
+     *
+     * @param asyncIterable - Optional byte stream or buffer to parse
+     * @param options - Configuration options for parsing
+     */
+    constructor(asyncIterable, options) {
+        this.byteBuffer =
+            asyncIterable instanceof ByteBuffer
+                ? asyncIterable
+                : new ByteBuffer(asyncIterable);
+        if (options?.separator) {
+            this.separator = options.separator;
+        }
+        if (options?.escapeChar) {
+            this.escapeChar = options.escapeChar;
+        }
+    }
+    set maxBufferSize(size) {
+        this.byteBuffer.maxBufferSize = size;
+    }
+    get maxBufferSize() {
+        return this.byteBuffer.maxBufferSize;
+    }
+    set allowBufferToBeExceeded(value) {
+        this.byteBuffer.allowBufferToBeExceeded = value;
+    }
+    get allowBufferToBeExceeded() {
+        return this.byteBuffer.allowBufferToBeExceeded;
+    }
+    /**
+     * Reads and parses the entire entity synchronously.
+     * Marks the entity as consumed after reading.
+     *
+     * @returns The parsed result of type T
+     */
+    read() {
+        const res = this.parse();
+        this.consumed = true;
+        return res;
+    }
+    /**
+     * Reads and parses the entire entity asynchronously.
+     * Marks the entity as consumed after reading.
+     *
+     * @returns A promise that resolves to the parsed result of type T
+     */
+    async readAsync() {
+        const res = await this.parseAsync();
+        this.consumed = true;
+        return res;
+    }
+    /**
+     * Returns a synchronous generator that yields chunks of type S.
+     * Marks the entity as consumed when iteration completes.
+     *
+     * @returns A generator that yields values of type S
+     */
+    *stream() {
+        const res = yield* this.streamImpl();
+        this.consumed = true;
+        return res;
+    }
+    /**
+     * Returns an asynchronous generator that yields chunks of type S.
+     * Handles buffering and automatically reads more data as needed.
+     *
+     * @returns An async generator that yields values of type S
+     */
+    async *streamAsync() {
+        while (true) {
+            const stream = this.stream();
+            let currentChunk = undefined;
+            while (true) {
+                currentChunk = this.byteBuffer.resetOnFail(() => stream.next());
+                if (currentChunk === undefined) {
+                    break; // Need more data
+                }
+                if (currentChunk.done) {
+                    return; // No more data
+                }
+                yield currentChunk.value;
+            }
+            await this.byteBuffer.readStreamAsync();
+        }
+    }
+    /**
+     * Consumes the entity if it hasn't been consumed yet.
+     * This ensures the buffer advances to the end of this entity.
+     */
+    consume() {
+        if (!this.consumed) {
+            this.read();
+        }
+    }
+    /**
+     * Asynchronously consumes the entity if it hasn't been consumed yet.
+     * This ensures the buffer advances to the end of this entity.
+     *
+     * @returns A promise that resolves when consumption is complete
+     */
+    async consumeAsync() {
+        if (!this.consumed) {
+            await this.readAsync();
+        }
+    }
+    /**
+     * Makes this entity iterable using the synchronous stream.
+     *
+     * @returns A generator that yields values of type S
+     */
+    [Symbol.iterator]() {
+        return this.stream();
+    }
+    /**
+     * Makes this entity async iterable using the asynchronous stream.
+     *
+     * @returns An async generator that yields values of type S
+     */
+    [Symbol.asyncIterator]() {
+        return this.streamAsync();
+    }
+}
+/**
+ * Represents a single CSV cell that can be read as a string or streamed in chunks.
+ * Handles quoted cells and escape sequences according to CSV standards.
+ */
+export class CsvCell extends CsvEntity {
+    chunkSize = DEFAULT_CHUNK_SIZE;
+    endOfLineReached = false;
+    parse() {
+        let str = '';
+        for (const part of this) {
+            str += part;
+        }
+        return str;
+    }
+    async parseAsync() {
+        let str = '';
+        for await (const part of this) {
+            str += part;
+        }
+        return str;
+    }
+    /**
+     * Reads the cell value and transforms it using the provided function.
+     * Special handling for Boolean transformer: converts 'true'/'false' strings to boolean.
+     *
+     * @typeParam T - The type to transform the cell value into
+     * @param transform - Function to transform the cell string into type T
+     * @returns The transformed value of type T
+     */
+    readAs(transform) {
+        const cellStr = this.read();
+        if (transform === Boolean) {
+            return (String(cellStr).toLowerCase() === 'true');
+        }
+        return transform(cellStr);
+    }
+    /**
+     * Asynchronously reads the cell value and transforms it using the provided function.
+     * Special handling for Boolean transformer: converts 'true'/'false' strings to boolean.
+     *
+     * @typeParam T - The type to transform the cell value into
+     * @param transform - Function to transform the cell string into type T (can be async)
+     * @returns A promise that resolves to the transformed value of type T
+     */
+    async readAsAsync(transform) {
+        const cellStr = await this.readAsync();
+        if (transform === Boolean) {
+            return (cellStr.toLowerCase() === 'true');
+        }
+        return await transform(cellStr);
+    }
+    *streamImpl() {
+        const separator = this.separator.charCodeAt(0);
+        const escapeChar = this.escapeChar.charCodeAt(0);
+        let chunk = [];
+        let hadData = false;
+        let isEscaped = false;
+        const next = this.byteBuffer.peek();
+        if (next === null && this.byteBuffer.eof) {
+            throw new Error('No more data to read');
+        }
+        if (next === escapeChar) {
+            isEscaped = true;
+            this.byteBuffer.expect(escapeChar); // consume opening quote
+        }
+        while (this.byteBuffer.peek() !== null) {
+            const next = this.byteBuffer.peek();
+            if (isEscaped) {
+                if (next === escapeChar) {
+                    // Possible end of quoted cell
+                    const lookahead = this.byteBuffer.peek(1);
+                    if (lookahead === escapeChar) {
+                        // Escaped quote
+                        this.byteBuffer.expect(escapeChar); // consume first quote
+                        this.byteBuffer.expect(escapeChar); // consume second quote
+                        chunk.push(escapeChar);
+                        continue;
+                    }
+                    else {
+                        // End of quoted cell
+                        break;
+                    }
+                }
+            }
+            else {
+                if (next === separator || isLineEnd(next)) {
+                    break;
+                }
+            }
+            const nextByte = this.byteBuffer.next();
+            chunk.push(nextByte);
+            if (chunk.length >= this.chunkSize) {
+                yield bytesToString(new Uint8Array(chunk));
+                chunk = [];
+                hadData = true;
+            }
+        }
+        if (isEscaped) {
+            this.byteBuffer.expect(escapeChar); // consume closing quote
+        }
+        if (this.byteBuffer.peek() === separator) {
+            this.byteBuffer.expect(separator); // consume separator
+        }
+        while (isLineEnd(this.byteBuffer.peek())) {
+            this.byteBuffer.next(); // consume line ending
+            this.endOfLineReached = true;
+        }
+        if (!hadData || chunk.length > 0)
+            yield bytesToString(new Uint8Array(chunk));
+    }
+}
+/**
+ * Represents a single CSV row that can be read as an array of strings or streamed as individual cells.
+ * Can also be parsed into an object using a shape definition.
+ *
+ * @typeParam T - The object type when reading as an object
+ * @typeParam O - The output type after optional transformation (defaults to T)
+ */
+export class CsvRow extends CsvEntity {
+    parse() {
+        const cells = [];
+        for (const cell of this) {
+            cells.push(cell.read());
+        }
+        return cells;
+    }
+    async parseAsync() {
+        const cells = [];
+        for await (const cell of this) {
+            cells.push(await cell.readAsync());
+        }
+        return cells;
+    }
+    *streamImpl() {
+        while (this.byteBuffer.peek() !== null) {
+            const cell = new CsvCell(this.byteBuffer, this);
+            yield cell;
+            cell.consume(); // Advance the buffer
+            if (cell.endOfLineReached) {
+                break;
+            }
+        }
+    }
+    /**
+     * Reads the row as an object using the provided shape definition.
+     * Handles column count validation and extra cells based on options.
+     *
+     * @param options - Configuration for reading the row as an object
+     * @returns The parsed object of type O
+     * @throws {TooManyColumnsError} If strictColumns is true and extra cells are found
+     * @throws {TooFewColumnsError} If strictColumns is true and cells are missing
+     */
+    readObject(options) {
+        let { shape, headers } = options;
+        let obj = {};
+        let i = 0;
+        const includeExtraCells = options?.includeExtraCells ?? false;
+        const strictColumns = options?.strictColumns ?? false;
+        if (Array.isArray(shape)) {
+            shape = shape.reduce((acc, header) => {
+                acc[header] = String;
+                return acc;
+            }, {});
+        }
+        for (const cell of this) {
+            if (!includeExtraCells && i >= headers.length) {
+                if (strictColumns) {
+                    throw new TooManyColumnsError(`Extra cells found${options?.rowIndex ? ` in row ${options.rowIndex}` : ''} but strictColumns is enabled`);
+                }
+                cell.consume();
+            }
+            else {
+                const header = i >= headers.length
+                    ? `extra_cell_${i - headers.length + 1}`
+                    : headers[i];
+                obj[header] = cell.read();
+            }
+            i++;
+            if (cell.endOfLineReached) {
+                break;
+            }
+        }
+        for (; i < headers.length; i++) {
+            if (strictColumns) {
+                throw new TooFewColumnsError(`Not enough cells${options?.rowIndex ? ` in row ${options.rowIndex}` : ''} to match headers when strictColumns is enabled`);
+            }
+            const header = headers[i];
+            obj[header] = undefined;
+        }
+        if (options.transform) {
+            obj = options.transform(obj);
+        }
+        for (const transform in shape) {
+            const transformer = shape[transform];
+            if (obj[transform] !== undefined) {
+                if (transformer === Boolean) {
+                    obj[transform] = String(obj[transform]) === 'true';
+                }
+                else {
+                    obj[transform] = transformer(obj[transform]);
+                }
+            }
+        }
+        this.consumed = true;
+        return obj;
+    }
+    /**
+     * Asynchronously reads the row as an object using the provided shape definition.
+     * Automatically handles buffer refills as needed.
+     *
+     * @param options - Configuration for reading the row as an object
+     * @returns A promise that resolves to the parsed object of type O
+     */
+    async readObjectAsync(options) {
+        while (true) {
+            const value = this.byteBuffer.resetOnFail(() => {
+                return this.readObject(options);
+            });
+            if (value !== undefined) {
+                return value;
+            }
+            await this.byteBuffer.readStreamAsync();
+        }
+    }
+}
+/**
+ * Main CSV parser class for parsing complete CSV documents.
+ * Supports reading headers, streaming rows, and converting rows to objects.
+ *
+ * @typeParam T - The object type for each row when reading as objects
+ * @typeParam O - The output type after optional transformation (defaults to T)
+ *
+ * @example
+ * ```typescript
+ * // Parse CSV with headers
+ * const csv = new Csv(fileStream)
+ * for await (const row of csv.streamObjectsAsync()) {
+ *   console.log(row)
+ * }
+ * ```
+ */
+export class Csv extends CsvEntity {
+    includeExtraCells = false;
+    ignoreUtf8Bom = true;
+    headers;
+    shape;
+    readHeaders = true;
+    strictColumns = false;
+    transform;
+    /**
+     * Creates a new CSV parser.
+     *
+     * @param asyncIterable - Optional byte stream or buffer containing CSV data
+     * @param options - Configuration options for CSV parsing
+     * @throws {Error} If both headers and shape options are specified
+     */
+    constructor(asyncIterable, options) {
+        super(asyncIterable, options);
+        if (options?.includeExtraCells) {
+            this.includeExtraCells = options.includeExtraCells;
+        }
+        if (options?.ignoreUtf8Bom !== undefined) {
+            this.ignoreUtf8Bom = options.ignoreUtf8Bom;
+        }
+        if (options?.headers) {
+            this.headers = options.headers;
+        }
+        if (options?.readHeaders !== undefined) {
+            this.readHeaders = options.readHeaders;
+        }
+        if (options?.strictColumns !== undefined) {
+            this.strictColumns = options.strictColumns;
+        }
+        if (options?.shape && this.headers) {
+            throw new Error('Cannot specify both headers and shape options');
+        }
+        this.shape = options?.shape;
+        this.transform = options?.transform;
+    }
+    readBom() {
+        // Skip UTF-8 BOM if present
+        while (this.ignoreUtf8Bom &&
+            this.byteBuffer.peek() === UTF_8_BOM[0] &&
+            this.byteBuffer.peek(1) === UTF_8_BOM[1] &&
+            this.byteBuffer.peek(2) === UTF_8_BOM[2]) {
+            this.byteBuffer.next();
+            this.byteBuffer.next();
+            this.byteBuffer.next();
+        }
+    }
+    parse() {
+        return Array.from(this.streamObjects());
+    }
+    async parseAsync() {
+        const results = [];
+        for await (const obj of this.streamObjectsAsync()) {
+            results.push(obj);
+        }
+        return results;
+    }
+    *streamImpl() {
+        // Skip UTF-8 BOM if present
+        this.readBom();
+        while (this.byteBuffer.peek() !== null) {
+            const row = new CsvRow(this.byteBuffer, this);
+            yield row;
+            row.consume(); // Advance the buffer
+        }
+        this.consumed = true;
+    }
+    /**
+     * Synchronously streams CSV rows as objects.
+     * Reads headers from the first row if readHeaders is true.
+     *
+     * @returns A generator that yields parsed objects of type O
+     *
+     * @example
+     * ```typescript
+     * const csv = new Csv(csvString)
+     * for (const row of csv.streamObjects()) {
+     *   console.log(row)
+     * }
+     * ```
+     */
+    *streamObjects() {
+        const stream = this.stream();
+        let headers = this.headers ?? [];
+        if (this.readHeaders) {
+            const headerRow = stream.next();
+            if (headerRow.done) {
+                return; // No data
+            }
+            const foundHeaders = headerRow.value.read();
+            if (headers.length === 0) {
+                headers = foundHeaders;
+            }
+        }
+        let rowIndex = this.readHeaders ? 2 : 1;
+        while (true) {
+            const currentRow = stream.next();
+            if (currentRow.done) {
+                return; // No more data
+            }
+            yield currentRow.value.readObject({
+                headers: headers,
+                shape: this.shape,
+                includeExtraCells: this.includeExtraCells,
+                strictColumns: this.strictColumns,
+                rowIndex: rowIndex++,
+                transform: this.transform,
+            });
+        }
+    }
+    /**
+     * Asynchronously streams CSV rows as objects.
+     * Automatically handles buffer refills as needed.
+     *
+     * @returns An async generator that yields parsed objects of type O
+     *
+     * @example
+     * ```typescript
+     * const csv = new Csv(fileStream)
+     * for await (const row of csv.streamObjectsAsync()) {
+     *   console.log(row)
+     * }
+     * ```
+     */
+    async *streamObjectsAsync() {
+        while (true) {
+            const stream = this.streamObjects();
+            let currentRow = undefined;
+            while (true) {
+                currentRow = this.byteBuffer.resetOnFail(() => stream.next());
+                if (currentRow === undefined) {
+                    break; // Need more data
+                }
+                if (currentRow.done) {
+                    return; // No more data
+                }
+                yield currentRow.value;
+            }
+            await this.byteBuffer.readStreamAsync();
+        }
+    }
+    /**
+     * Static method to stringify an array of objects into CSV format.
+     * Returns a synchronous generator that yields CSV string chunks.
+     *
+     * @typeParam T - The input object type
+     * @typeParam O - The output object type after optional transformation (defaults to T)
+     * @param values - Array of objects to convert to CSV
+     * @param options - Optional configuration for CSV stringification
+     * @returns A generator that yields CSV string chunks
+     *
+     * @example
+     * ```typescript
+     * const data = [{ name: 'Alice', age: 30 }, { name: 'Bob', age: 25 }]
+     * for (const chunk of Csv.stringify(data, { headers: ['name', 'age'] })) {
+     *   process.stdout.write(chunk)
+     * }
+     * ```
+     */
+    static stringify(values, options) {
+        return new CsvStringify(values, options).toStream();
+    }
+    /**
+     * Static method to stringify an array of objects into CSV format asynchronously.
+     * Returns an asynchronous generator that yields CSV string chunks.
+     *
+     * @typeParam T - The input object type
+     * @typeParam O - The output object type after optional transformation (defaults to T)
+     * @param values - Array of objects to convert to CSV
+     * @param options - Optional configuration for CSV stringification
+     * @returns An async generator that yields CSV string chunks
+     *
+     * @example
+     * ```typescript
+     * const data = [{ name: 'Alice', age: 30 }, { name: 'Bob', age: 25 }]
+     * for await (const chunk of Csv.stringifyAsync(data)) {
+     *   process.stdout.write(chunk)
+     * }
+     * ```
+     */
+    static stringifyAsync(values, options) {
+        return new CsvStringify(values, options).toStreamAsync();
+    }
+    /**
+     * Static method to create a CsvStringify instance for advanced usage.
+     *
+     * @typeParam T - The input object type
+     * @typeParam O - The output object type after optional transformation (defaults to T)
+     * @param values - Array of objects to convert to CSV
+     * @param options - Optional configuration for CSV stringification
+     * @returns A CsvStringify instance
+     */
+    static stringifier(values, options) {
+        return new CsvStringify(values, options);
+    }
+}

package/dist/stringify.d.ts

@@ -0,0 +1,91 @@
+import { CsvObjectShape, CsvString } from './types.js';
+export interface CsvStringifyOptions<T extends object = object, O extends object = T> {
+    /** Optional array of headers to use as the first row. Optionally, pass in a CsvObjectShape to be used as headers */
+    headers?: string[] | CsvObjectShape<T>;
+    /** Character to separate fields (default: ',') */
+    delimiter?: string;
+    /** Character to escape special characters (default: '"') */
+    escapeChar?: string;
+    /** Character to quote fields (default: '"') */
+    quoteChar?: string;
+    /** Newline character (default: '\n') */
+    newline?: string;
+    /** Whether to write a UTF-8 BOM at the start of the output (default: false) */
+    writeBom?: boolean;
+    /** Whether to always write headers, even if there are no records (default: false) */
+    alwaysWriteHeaders?: boolean;
+    /** Optional transform function to modify each record before stringifying */
+    transform?: (row: T) => O;
+}
+/**
+ * CSV stringifier class for converting JavaScript objects into CSV format.
+ * Supports both synchronous and asynchronous streaming of CSV output.
+ *
+ * @typeParam T - The input object type
+ * @typeParam O - The output object type after optional transformation (defaults to T)
+ *
+ * @example
+ * ```typescript
+ * const data = [{ name: 'Alice', age: 30 }, { name: 'Bob', age: 25 }]
+ * const stringifier = new CsvStringify(data, { headers: ['name', 'age'] })
+ * const csvString = stringifier.toString()
+ * ```
+ */
+export declare class CsvStringify<T extends object = object, O extends object = T> {
+    private values;
+    headers?: string[];
+    delimiter: string;
+    escapeChar: string;
+    quoteChar: string;
+    newline: string;
+    writeBom: boolean;
+    alwaysWriteHeaders: boolean;
+    transform?: (row: T) => O;
+    /**
+     * Creates a new CSV stringifier.
+     *
+     * @param values - Iterable or async iterable of objects to stringify
+     * @param options - Optional configuration for CSV stringification
+     */
+    constructor(values: Iterable<T> | AsyncIterable<T>, options?: CsvStringifyOptions<T, O>);
+    private formatField;
+    private recordToString;
+    private forceWriteHeaders;
+    /**
+     * Returns a synchronous generator that yields CSV string chunks.
+     *
+     * @returns A generator that yields CSV strings
+     * @throws {Error} If values is not iterable
+     */
+    toStream(): Generator<CsvString<O>>;
+    /**
+     * Returns an asynchronous generator that yields CSV string chunks.
+     *
+     * @returns An async generator that yields CSV strings
+     */
+    toStreamAsync(): AsyncGenerator<CsvString<O>>;
+    /**
+     * Converts all values to a single CSV string synchronously.
+     *
+     * @returns The complete CSV string
+     */
+    toString(): CsvString<O>;
+    /**
+     * Converts all values to a single CSV string asynchronously.
+     *
+     * @returns A promise that resolves to the complete CSV string
+     */
+    toStringAsync(): Promise<CsvString<O>>;
+    /**
+     * Makes this stringifier iterable using the synchronous stream.
+     *
+     * @returns A generator that yields CSV strings
+     */
+    [Symbol.iterator](): Generator<CsvString<O>>;
+    /**
+     * Makes this stringifier async iterable using the asynchronous stream.
+     *
+     * @returns An async generator that yields CSV strings
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<CsvString<O>>;
+}