csv-stream-lite 0.1.0

package/dist/byte-buffer.js

@@ -0,0 +1,282 @@
+import { DEFAULT_MAX_BUFFER_SIZE } from './defaults.js';
+import { BufferSizeExceededError, EofReachedError, NoMoreTokensError, } from './errors.js';
+import { bytesToString, stringToBytes } from './utils.js';
+/**
+ * Converts a ReadableStream into an AsyncIterable.
+ *
+ * @param stream - The ReadableStream to convert
+ * @returns An AsyncIterable that yields items from the stream
+ */
+function readableStreamToAsyncIterable(stream) {
+    const reader = stream.getReader();
+    return {
+        async *[Symbol.asyncIterator]() {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) {
+                    break;
+                }
+                yield value;
+            }
+        },
+    };
+}
+/**
+ * A buffer for managing byte-level input with support for async streams.
+ * Provides lookahead, consumption tracking, and buffer compaction capabilities.
+ */
+export class ByteBuffer {
+    /** Maximum size of the buffer before compaction */
+    maxBufferSize = DEFAULT_MAX_BUFFER_SIZE;
+    /** Whether end of file has been signaled */
+    eof = false;
+    /** Current position in the buffer */
+    bufferIndex = 0;
+    /** Whether the buffer is locked against compaction */
+    locked = false;
+    /** Whether to allow exceeding the buffer size temporarily */
+    allowBufferToBeExceeded = true;
+    /** Current position in the input stream */
+    inputOffset = 0;
+    /** Number of outputs generated */
+    outputOffset = 0;
+    /** Buffer holding input items */
+    buffer = [];
+    /** Optional async iterable input source */
+    asyncIterable;
+    /**
+     * Creates a new ByteBuffer instance.
+     *
+     * @param asyncIterable - Optional async iterable source for streaming input
+     */
+    constructor(asyncIterable) {
+        this.asyncIterable =
+            asyncIterable instanceof ReadableStream
+                ? readableStreamToAsyncIterable(asyncIterable)
+                : typeof asyncIterable === 'string'
+                    ? (function* () {
+                        yield* [asyncIterable];
+                    })()
+                    : asyncIterable;
+    }
+    /**
+     * Reads data from the stream into the buffer.
+     * Reads up to maxBufferSize bytes at a time.
+     */
+    readStream() {
+        if (!this.asyncIterable || !(Symbol.iterator in this.asyncIterable)) {
+            return false;
+        }
+        const iterator = this.asyncIterable[Symbol.iterator]();
+        let processed = false;
+        while (this.length < this.maxBufferSize || !processed) {
+            const next = iterator.next();
+            processed = true;
+            if (next.done) {
+                this.eof = true;
+                break;
+            }
+            const value = next.value;
+            this.feed(value);
+        }
+        return processed;
+    }
+    /**
+     * Reads data from the sync or async stream into the buffer.
+     * Reads up to maxBufferSize bytes at a time.
+     */
+    async readStreamAsync() {
+        this.readStream();
+        if (!this.asyncIterable ||
+            !(Symbol.asyncIterator in this.asyncIterable)) {
+            return;
+        }
+        const iterator = this.asyncIterable[Symbol.asyncIterator]();
+        let processed = false;
+        while (this.length < this.maxBufferSize || !processed) {
+            processed = true;
+            const next = await iterator.next();
+            if (next.done) {
+                this.eof = true;
+                return;
+            }
+            const value = next.value;
+            this.feed(value);
+        }
+    }
+    /**
+     * Gets the current length of the buffer.
+     *
+     * @returns The number of bytes in the buffer
+     */
+    get length() {
+        return this.buffer.length;
+    }
+    /**
+     * Feeds input items into the parser buffer.
+     *
+     * @param input - Input items to add to the buffer
+     */
+    feed(...input) {
+        for (const item of input) {
+            if (Array.isArray(item)) {
+                for (const subItem of item) {
+                    this.push(subItem);
+                }
+                continue;
+            }
+            else if (item instanceof Uint8Array) {
+                for (const subItem of item) {
+                    this.push(subItem);
+                }
+                continue;
+            }
+            else if (typeof item === 'string') {
+                const encoded = stringToBytes(item);
+                for (const byte of encoded) {
+                    this.push(byte);
+                }
+                continue;
+            }
+            this.push(item);
+        }
+    }
+    push(byte) {
+        if (!this.allowBufferToBeExceeded &&
+            this.buffer.length >= this.maxBufferSize) {
+            throw new BufferSizeExceededError('Buffer size exceeded maximum limit');
+        }
+        this.buffer.push(byte);
+    }
+    /**
+     * Checks if end of file has been reached and buffer is exhausted.
+     *
+     * @returns True if no more input is available
+     */
+    atEof() {
+        return this.eof && this.bufferIndex >= this.buffer.length;
+    }
+    /**
+     * Peeks at an item in the buffer without consuming it.
+     *
+     * @param ahead - Number of positions to look ahead (default: 0)
+     * @returns The item at the peek position, or null if at EOF
+     * @throws NoMoreTokensError if more input is needed and EOF not signaled
+     */
+    peek(ahead = 0) {
+        const index = this.bufferIndex + ahead;
+        if (index >= this.buffer.length) {
+            if (!this.eof) {
+                if (!this.readStream()) {
+                    throw new NoMoreTokensError('No more items available');
+                }
+                else {
+                    return this.peek(ahead);
+                }
+            }
+            return null;
+        }
+        return this.buffer[index];
+    }
+    /**
+     * Consumes and returns the next item from the buffer.
+     *
+     * @returns The next item
+     * @throws NoMoreTokensError if more input is needed and EOF not signaled
+     * @throws EofReachedError if at EOF and no more items available
+     */
+    next() {
+        if (this.bufferIndex >= this.buffer.length) {
+            if (this.readStream()) {
+                return this.next();
+            }
+            if (!this.eof) {
+                throw new NoMoreTokensError('No more items available');
+            }
+            throw new EofReachedError('End of file reached');
+        }
+        this.inputOffset++;
+        return this.buffer[this.bufferIndex++];
+    }
+    /**
+     * Consumes and validates the next item against an expected type or value.
+     *
+     * @typeParam T - The expected item type
+     * @param itemType - Constructor or value to match against
+     * @returns The consumed item cast to the expected type
+     * @throws Error if the item doesn't match the expected type/value
+     */
+    expect(itemType) {
+        const item = this.next();
+        if (item !== itemType) {
+            throw new Error(`Expected ${itemType} but got ${item}`);
+        }
+        return itemType;
+    }
+    /**
+     * Compacts the buffer by removing consumed items
+     */
+    compact() {
+        if (!this.locked && this.bufferIndex > 0) {
+            this.buffer = this.buffer.slice(this.bufferIndex);
+            this.bufferIndex = 0;
+        }
+    }
+    /**
+     * Override to customize when to compact the buffer
+     * By default, compacts when more than maxBufferSize bytes have been consumed
+     *
+     * @returns boolean indicating whether to compact the buffer
+     */
+    canCompact() {
+        return this.bufferIndex > this.maxBufferSize;
+    }
+    /**
+     * Attempts to execute a function, resetting buffer position on failure.
+     * Useful for speculative parsing attempts that may need to be retried.
+     *
+     * @typeParam T - The return type of the try function
+     * @param tryFn - Function to attempt execution
+     * @param onFail - Optional callback invoked on failure
+     * @returns The result of tryFn if successful, undefined if NoMoreTokensError thrown
+     */
+    resetOnFail(tryFn, onFail) {
+        const bufferIndex = this.bufferIndex;
+        try {
+            const result = tryFn();
+            if (this.canCompact()) {
+                this.compact();
+            }
+            return result;
+        }
+        catch (e) {
+            if (e instanceof NoMoreTokensError) {
+                this.bufferIndex = bufferIndex;
+                onFail?.(e);
+            }
+            else {
+                throw e;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Returns a string representation of the buffer state for debugging.
+     *
+     * @returns A formatted string showing buffer contents and state
+     */
+    toString() {
+        return [
+            'ByteBuffer {',
+            `  buffer: [${this.buffer.join(', ')}],`,
+            `  bufferIndex: ${this.bufferIndex},`,
+            `  inputOffset: ${this.inputOffset},`,
+            `  outputOffset: ${this.outputOffset},`,
+            `  eof: ${this.eof},`,
+            `  as string: ${bytesToString(new Uint8Array(this.buffer))}`,
+            '  as string from bufferIndex: ' +
+                bytesToString(new Uint8Array(this.buffer.slice(this.bufferIndex))),
+            '}',
+        ].join('\n');
+    }
+}

package/dist/defaults.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Default maximum buffer size before compaction
+ */
+export declare const DEFAULT_MAX_BUFFER_SIZE: number;
+/**
+ * Default chunk size for reading cells
+ */
+export declare const DEFAULT_CHUNK_SIZE: number;

package/dist/defaults.js

@@ -0,0 +1,8 @@
+/**
+ * Default maximum buffer size before compaction
+ */
+export const DEFAULT_MAX_BUFFER_SIZE = 1024 * 100; // 100 KB
+/**
+ * Default chunk size for reading cells
+ */
+export const DEFAULT_CHUNK_SIZE = 1024 * 10; // 10 KB

package/dist/errors.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Base error class for CSV Stream Lite errors.
+ */
+export declare class CsvStreamLiteError extends Error {
+}
+/**
+ * Error thrown when the buffer is empty and more input is needed.
+ */
+export declare class NoMoreTokensError extends CsvStreamLiteError {
+}
+/**
+ * Error thrown when the end of file has been reached and no more items are available.
+ */
+export declare class EofReachedError extends CsvStreamLiteError {
+}
+/**
+ * Error thrown when the buffer size limit is exceeded.
+ */
+export declare class BufferSizeExceededError extends CsvStreamLiteError {
+}
+/**
+ * Error thrown when a CSV row has more columns than expected when `strictColumns` is enabled.
+ */
+export declare class TooManyColumnsError extends CsvStreamLiteError {
+}
+/**
+ * Error thrown when a CSV row has fewer columns than expected when `strictColumns` is enabled.
+ */
+export declare class TooFewColumnsError extends CsvStreamLiteError {
+}

package/dist/errors.js

@@ -0,0 +1,30 @@
+/**
+ * Base error class for CSV Stream Lite errors.
+ */
+export class CsvStreamLiteError extends Error {
+}
+/**
+ * Error thrown when the buffer is empty and more input is needed.
+ */
+export class NoMoreTokensError extends CsvStreamLiteError {
+}
+/**
+ * Error thrown when the end of file has been reached and no more items are available.
+ */
+export class EofReachedError extends CsvStreamLiteError {
+}
+/**
+ * Error thrown when the buffer size limit is exceeded.
+ */
+export class BufferSizeExceededError extends CsvStreamLiteError {
+}
+/**
+ * Error thrown when a CSV row has more columns than expected when `strictColumns` is enabled.
+ */
+export class TooManyColumnsError extends CsvStreamLiteError {
+}
+/**
+ * Error thrown when a CSV row has fewer columns than expected when `strictColumns` is enabled.
+ */
+export class TooFewColumnsError extends CsvStreamLiteError {
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './parser.js';
+export * from './stringify.js';
+export * from './errors.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './parser.js';
+export * from './stringify.js';
+export * from './errors.js';

package/dist/parser.d.ts

@@ -0,0 +1,293 @@
+import { ByteBuffer } from './byte-buffer.js';
+import { CsvStringify, CsvStringifyOptions } from './stringify.js';
+import { ByteStream, CsvObjectShape, CsvString } from './types.js';
+/**
+ * Options for configuring CSV entity parsing.
+ */
+export interface CsvEntityOptions {
+    /** Character used to separate fields. Defaults to ',' */
+    separator?: string;
+    /** Character used to escape special characters. Defaults to '"' */
+    escapeChar?: string;
+}
+/**
+ * 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 declare abstract class CsvEntity<T, S = T> implements Required<CsvEntityOptions> {
+    byteBuffer: ByteBuffer;
+    separator: string;
+    escapeChar: string;
+    consumed: boolean;
+    /**
+     * Creates a new CSV entity.
+     *
+     * @param asyncIterable - Optional byte stream or buffer to parse
+     * @param options - Configuration options for parsing
+     */
+    constructor(asyncIterable?: ByteStream | ByteBuffer, options?: CsvEntityOptions);
+    set maxBufferSize(size: number);
+    get maxBufferSize(): number;
+    set allowBufferToBeExceeded(value: boolean);
+    get allowBufferToBeExceeded(): boolean;
+    protected abstract parse(): T;
+    protected abstract parseAsync(): Promise<T>;
+    protected abstract streamImpl(): Generator<S>;
+    /**
+     * Reads and parses the entire entity synchronously.
+     * Marks the entity as consumed after reading.
+     *
+     * @returns The parsed result of type T
+     */
+    read(): T;
+    /**
+     * 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
+     */
+    readAsync(): Promise<T>;
+    /**
+     * 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(): Generator<S>;
+    /**
+     * 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
+     */
+    streamAsync(): AsyncGenerator<S>;
+    /**
+     * Consumes the entity if it hasn't been consumed yet.
+     * This ensures the buffer advances to the end of this entity.
+     */
+    consume(): void;
+    /**
+     * 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
+     */
+    consumeAsync(): Promise<void>;
+    /**
+     * Makes this entity iterable using the synchronous stream.
+     *
+     * @returns A generator that yields values of type S
+     */
+    [Symbol.iterator](): Generator<S>;
+    /**
+     * Makes this entity async iterable using the asynchronous stream.
+     *
+     * @returns An async generator that yields values of type S
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<S>;
+}
+/**
+ * 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 declare class CsvCell extends CsvEntity<string> {
+    chunkSize: number;
+    endOfLineReached: boolean;
+    protected parse(): string;
+    protected parseAsync(): Promise<string>;
+    /**
+     * 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<T>(transform: (cell: string) => T): T;
+    /**
+     * 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
+     */
+    readAsAsync<T>(transform: (cell: string) => Promise<T> | T): Promise<T>;
+    protected streamImpl(): Generator<string>;
+}
+/**
+ * Options for reading a CSV row as an object.
+ *
+ * @typeParam T - The object type with headers as keys
+ * @typeParam O - The output type after optional transformation (defaults to T)
+ */
+export interface CsvRowObjectOptions<T extends object, I = unknown> {
+    /** Headers for the CSV row */
+    headers: string[];
+    /** Shape definition mapping headers to type transformers, or an array of header names */
+    shape?: CsvObjectShape<T>;
+    /** Optional row index for error messages */
+    rowIndex?: number;
+    /** Whether to include extra cells beyond defined headers. Defaults to false */
+    includeExtraCells?: boolean;
+    /** Whether to enforce exact column count matching headers. Defaults to false */
+    strictColumns?: boolean;
+    /** Optional function to transform the parsed row object */
+    transform?: (row: I) => T;
+}
+/**
+ * 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 declare class CsvRow<T extends object = object, I = unknown> extends CsvEntity<string[], CsvCell> {
+    protected parse(): string[];
+    protected parseAsync(): Promise<string[]>;
+    protected streamImpl(): Generator<CsvCell>;
+    /**
+     * 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: CsvRowObjectOptions<T, I>): T;
+    /**
+     * 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
+     */
+    readObjectAsync(options: CsvRowObjectOptions<T, I>): Promise<T>;
+}
+/**
+ * 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 declare class Csv<T extends object, I = unknown> extends CsvEntity<T[], CsvRow<T, I>> {
+    includeExtraCells: boolean;
+    ignoreUtf8Bom: boolean;
+    headers?: string[];
+    shape?: CsvObjectShape<T>;
+    readHeaders: boolean;
+    strictColumns: boolean;
+    transform?: (row: I) => T;
+    /**
+     * 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?: ByteStream<T> | ByteBuffer, options?: CsvEntityOptions & {
+        includeExtraCells?: boolean;
+        ignoreUtf8Bom?: boolean;
+        readHeaders?: boolean;
+        headers?: string[];
+        shape?: CsvObjectShape<T>;
+        strictColumns?: boolean;
+        transform?: (row: I) => T;
+    });
+    private readBom;
+    protected parse(): T[];
+    protected parseAsync(): Promise<T[]>;
+    protected streamImpl(): Generator<CsvRow<T>>;
+    /**
+     * 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(): Generator<T>;
+    /**
+     * 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)
+     * }
+     * ```
+     */
+    streamObjectsAsync(): AsyncGenerator<T>;
+    /**
+     * 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<T extends object, O extends object = T>(values: T[], options?: CsvStringifyOptions<T, T extends O ? T : O>): Generator<CsvString<T extends O ? T : O>>;
+    /**
+     * 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<T extends object, O extends object = T>(values: T[], options?: CsvStringifyOptions<T, T extends O ? T : O>): AsyncGenerator<CsvString<T extends O ? T : O>>;
+    /**
+     * 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<T extends object, O extends object = T>(values: T[], options?: CsvStringifyOptions<T, T extends O ? T : O>): CsvStringify<T, T extends O ? T : O>;
+}