@cj-tech-master/excelts 5.1.18 → 6.0.0-beta.1

package/dist/browser/modules/csv/stream/parser.js

@@ -0,0 +1,928 @@
+/**
+ * CSV Parser Stream
+ *
+ * True streaming CSV parser using cross-platform stream module.
+ * Works identically in both Node.js and Browser environments.
+ */
+import { Transform } from "../../stream/index.browser.js";
+import { isSyncTransform, isSyncValidate } from "../types.js";
+import { detectDelimiter, stripBom } from "../utils/detect.js";
+import { applyDynamicTypingToRow, applyDynamicTypingToArrayRow } from "../utils/dynamic-typing.js";
+import { convertRowToObject, filterValidHeaders } from "../parse/helpers.js";
+import { DEFAULT_LINEBREAK_REGEX, getUtf8ByteLength } from "../constants.js";
+import { splitLinesWithEndings } from "../parse/lines.js";
+import { createParseConfig, toScannerConfig } from "../parse/config.js";
+import { createParseState, getUnquotedArray } from "../parse/state.js";
+import { processCompletedRow as processCompletedRowCore, shouldSkipRow as shouldSkipRowCore } from "../parse/row-processor.js";
+// Import Scanner for efficient batch scanning
+import { createScanner } from "../parse/scanner/index.js";
+/**
+ * Transform stream that parses CSV data row by row
+ *
+ * @example
+ * ```ts
+ * const parser = new CsvParserStream({ headers: true });
+ * readable.pipe(parser).on('data', (row) => console.log(row));
+ * ```
+ */
+export class CsvParserStream extends Transform {
+    constructor(options = {}) {
+        // In objectMode (default), emit Row objects; when objectMode === false, emit JSON strings.
+        super({ objectMode: options.objectMode !== false });
+        /**
+         * Shared sink array for processCompletedRowCore's errors parameter.
+         * The streaming parser emits errors via 'data-invalid' events instead,
+         * so this array is cleared after each call to prevent unbounded growth.
+         */
+        this.parseErrorsSink = [];
+        // -------------------------------------------------------------------------
+        // Streaming-specific state (not in parse-core)
+        // -------------------------------------------------------------------------
+        this.buffer = "";
+        this._rowTransform = null;
+        this._rowValidator = null;
+        // Delimiter detection
+        this.autoDetectDelimiter = false;
+        this.delimiterDetected = false;
+        // Chunk callback support
+        this.chunkBuffer = [];
+        this.totalRowsProcessed = 0;
+        this.isFirstChunk = true;
+        this.chunkAborted = false;
+        // Pre-processing flags
+        this.beforeFirstChunkApplied = false;
+        this.bomStripped = false;
+        // Stream control
+        this.toLineReached = false;
+        this.headersEmitted = false;
+        this.totalCharsProcessed = 0;
+        // Backpressure handling
+        this.backpressure = false;
+        this.pendingCallback = null;
+        this.options = options;
+        this.chunkSize = options.chunkSize ?? 1000;
+        // Reuse a single decoder instance and enable streaming decode to correctly handle
+        // multi-byte characters split across chunks.
+        // Use options.encoding if provided (default: utf-8)
+        this.decoder = new TextDecoder(options.encoding || "utf-8");
+        // Check if auto-detection is requested (delimiter === "")
+        const delimiterOption = options.delimiter ?? ",";
+        this.autoDetectDelimiter = delimiterOption === "";
+        // Create unified config and state using parse-core factory
+        const { config } = createParseConfig({ options });
+        this.parseConfig = config;
+        this.parseState = createParseState(config);
+        // Create Scanner instance for efficient batch scanning
+        this.scanner = createScanner(toScannerConfig(config));
+        // Apply transform/validate from options if provided
+        if (options.rowTransform) {
+            this.transform(options.rowTransform);
+        }
+        if (options.validate) {
+            this.validate(options.validate);
+        }
+    }
+    /**
+     * Called when downstream is ready for more data (backpressure released).
+     * Resume processing if we were paused due to backpressure.
+     */
+    _read(_size) {
+        if (this.backpressure && this.pendingCallback) {
+            this.backpressure = false;
+            const callback = this.pendingCallback;
+            this.pendingCallback = null;
+            // Resume processing
+            callback();
+        }
+    }
+    /**
+     * Set a transform function to modify rows before emitting
+     * Supports both sync and async transforms
+     */
+    transform(transformFunction) {
+        if (typeof transformFunction !== "function") {
+            throw new TypeError("The transform should be a function");
+        }
+        if (isSyncTransform(transformFunction)) {
+            this._rowTransform = (row, cb) => {
+                try {
+                    const result = transformFunction(row);
+                    cb(null, result);
+                }
+                catch (e) {
+                    cb(e);
+                }
+            };
+        }
+        else {
+            this._rowTransform = transformFunction;
+        }
+        return this;
+    }
+    /**
+     * Set a validate function to filter rows
+     * Invalid rows emit 'data-invalid' event
+     */
+    validate(validateFunction) {
+        if (typeof validateFunction !== "function") {
+            throw new TypeError("The validate should be a function");
+        }
+        if (isSyncValidate(validateFunction)) {
+            this._rowValidator = (row, cb) => {
+                try {
+                    const result = validateFunction(row);
+                    if (typeof result === "boolean") {
+                        cb(null, result);
+                    }
+                    else {
+                        cb(null, result.isValid, result.reason);
+                    }
+                }
+                catch (e) {
+                    cb(e);
+                }
+            };
+        }
+        else {
+            this._rowValidator = validateFunction;
+        }
+        return this;
+    }
+    _transform(chunk, _encoding, callback) {
+        // If chunk callback aborted parsing or toLine reached, skip all further processing
+        if (this.chunkAborted || this.toLineReached) {
+            callback();
+            return;
+        }
+        try {
+            const data = typeof chunk === "string" ? chunk : this.decoder.decode(chunk, { stream: true });
+            this.buffer += data;
+            // Apply beforeFirstChunk on first chunk
+            if (!this.beforeFirstChunkApplied && this.options.beforeFirstChunk) {
+                this.beforeFirstChunkApplied = true;
+                const result = this.options.beforeFirstChunk(this.buffer);
+                if (typeof result === "string") {
+                    this.buffer = result;
+                }
+            }
+            // Strip BOM once, after beforeFirstChunk
+            if (!this.bomStripped) {
+                this.buffer = stripBom(this.buffer);
+                this.bomStripped = true;
+            }
+            // Auto-detect delimiter on first chunk if requested
+            // Defer detection if buffer only contains comments/empty lines
+            if (this.autoDetectDelimiter && !this.delimiterDetected) {
+                // Quick check: find first non-comment, non-empty line without full split
+                const comment = this.options.comment;
+                let hasDataLine = false;
+                let start = 0;
+                const bufLen = this.buffer.length;
+                while (start < bufLen) {
+                    // Find end of line
+                    let end = start;
+                    while (end < bufLen && this.buffer[end] !== "\n" && this.buffer[end] !== "\r") {
+                        end++;
+                    }
+                    const line = this.buffer.slice(start, end).trim();
+                    if (line !== "" && (!comment || !line.startsWith(comment))) {
+                        hasDataLine = true;
+                        break;
+                    }
+                    // Skip past newline(s)
+                    start = end;
+                    if (start < bufLen && this.buffer[start] === "\r") {
+                        start++;
+                    }
+                    if (start < bufLen && this.buffer[start] === "\n") {
+                        start++;
+                    }
+                    if (start === end) {
+                        break;
+                    } // No progress, avoid infinite loop
+                }
+                if (hasDataLine) {
+                    const shouldSkipEmpty = this.options.skipEmptyLines;
+                    this.parseConfig.delimiter = detectDelimiter(this.buffer, this.parseConfig.quote || '"', this.options.delimitersToGuess, this.options.comment, shouldSkipEmpty);
+                    this.delimiterDetected = true;
+                    // Emit delimiter event so consumers can know which delimiter was detected
+                    this.emit("delimiter", this.parseConfig.delimiter);
+                    // Re-create Scanner with the detected delimiter
+                    this.scanner = createScanner(toScannerConfig(this.parseConfig));
+                }
+            }
+            this.processBuffer(callback);
+        }
+        catch (error) {
+            callback(error);
+        }
+    }
+    _flush(callback) {
+        // If chunk callback aborted parsing or toLine reached, skip flush
+        if (this.chunkAborted || this.toLineReached) {
+            callback();
+            return;
+        }
+        try {
+            const remainingDecoded = this.decoder.decode();
+            if (remainingDecoded) {
+                this.buffer += remainingDecoded;
+            }
+            if (this.buffer) {
+                this.processBuffer(err => {
+                    if (err) {
+                        callback(err);
+                        return;
+                    }
+                    this.flushCurrentRow(err2 => {
+                        if (err2) {
+                            callback(err2);
+                            return;
+                        }
+                        this.flushFinalChunk(callback);
+                    });
+                });
+                return;
+            }
+            this.flushCurrentRow(err => {
+                if (err) {
+                    callback(err);
+                    return;
+                }
+                this.flushFinalChunk(callback);
+            });
+        }
+        catch (error) {
+            callback(error);
+        }
+    }
+    /**
+     * Clean up resources when stream is destroyed.
+     * Handles pending backpressure callbacks and clears buffers.
+     */
+    _destroy(error, callback) {
+        // Clear pending backpressure callback to prevent memory leaks
+        // The callback is not invoked - the stream is being destroyed
+        this.pendingCallback = null;
+        this.backpressure = false;
+        // Clear buffers
+        this.buffer = "";
+        this.chunkBuffer = [];
+        // Reset scanner if present
+        this.scanner.reset();
+        callback(error);
+    }
+    flushCurrentRow(callback) {
+        // If toLine was reached, don't process remaining data
+        if (this.toLineReached) {
+            callback();
+            return;
+        }
+        // In fastMode, parsing is line-based and does not use currentField/currentRow.
+        // Flush any remaining buffer as a final line when there's no trailing newline.
+        if (this.parseConfig.fastMode) {
+            this.flushFastModeRemainder(callback);
+            return;
+        }
+        // Use Scanner's flush to process any remaining data at EOF
+        const scanResult = this.scanner.flush();
+        if (!scanResult || scanResult.fields.length === 0) {
+            callback();
+            return;
+        }
+        // Apply trim to fields.
+        // Note: scanResult.fields is reused by the streaming scanner; we must copy even when trim is identity.
+        const row = this.parseConfig.trimFieldIsIdentity
+            ? scanResult.fields.slice()
+            : scanResult.fields.map(this.parseConfig.trimField);
+        const pendingRows = [];
+        const action = this._handleParsedRow({
+            fields: row,
+            charLength: 0, // flush — no further offset tracking needed
+            raw: scanResult.raw,
+            quoted: scanResult.quoted,
+            pendingRows,
+            shouldSkipEmpty: this.options.skipEmptyLines || false,
+            skipLines: this.options.skipLines ?? 0,
+            callback
+        });
+        if (action === "stop" || action === "error") {
+            return;
+        }
+        this.processPendingRows(pendingRows, callback);
+    }
+    flushFastModeRemainder(callback) {
+        let line = this.buffer;
+        this.buffer = "";
+        // Handle trailing CR that might be from a split CRLF
+        // In _flush, there's no more data coming, so trailing \r is a line ending, not content
+        if (line.endsWith("\r")) {
+            line = line.slice(0, -1);
+        }
+        if (line === "") {
+            callback();
+            return;
+        }
+        const pendingRows = [];
+        const row = line.split(this.parseConfig.delimiter);
+        const trimmedRow = this.parseConfig.trimFieldIsIdentity
+            ? row
+            : row.map(this.parseConfig.trimField);
+        // In fast mode, no fields are quoted
+        const quoted = this.parseConfig.infoOption ? getUnquotedArray(trimmedRow.length) : undefined;
+        const action = this._handleParsedRow({
+            fields: trimmedRow,
+            charLength: 0, // flush — no further offset tracking needed
+            raw: line,
+            quoted,
+            pendingRows,
+            shouldSkipEmpty: this.options.skipEmptyLines || false,
+            skipLines: this.options.skipLines ?? 0,
+            callback
+        });
+        if (action === "stop" || action === "error") {
+            return;
+        }
+        this.processPendingRows(pendingRows, callback);
+    }
+    /**
+     * Push buffered rows to stream with backpressure support
+     * @returns false if backpressure is applied (downstream is full)
+     */
+    pushBufferedRows(rows) {
+        const useJson = this.options.objectMode === false;
+        for (const row of rows) {
+            const canContinue = this.push(useJson ? JSON.stringify(row) : row);
+            if (!canContinue) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Push a single row to stream with backpressure support
+     * @returns false if backpressure is applied (downstream is full)
+     */
+    pushRow(row) {
+        const useJson = this.options.objectMode === false;
+        return this.push(useJson ? JSON.stringify(row) : row);
+    }
+    /**
+     * Invoke chunk callback and handle result (sync or async)
+     */
+    invokeChunkCallback(rows, meta, callback) {
+        const result = this.options.chunk(rows, meta);
+        if (result instanceof Promise) {
+            result
+                .then(shouldContinue => {
+                if (shouldContinue === false) {
+                    this.chunkAborted = true;
+                }
+                callback();
+            })
+                .catch(err => callback(err));
+        }
+        else {
+            if (result === false) {
+                this.chunkAborted = true;
+            }
+            callback();
+        }
+    }
+    /**
+     * Flush any remaining rows in the chunk buffer at the end of the stream
+     */
+    flushFinalChunk(callback) {
+        if (this.chunkBuffer.length > 0 && this.options.chunk) {
+            const chunkRowCount = this.chunkBuffer.length;
+            const cursor = this.totalRowsProcessed - chunkRowCount;
+            const meta = {
+                cursor,
+                rowCount: chunkRowCount,
+                isFirstChunk: this.isFirstChunk,
+                isLastChunk: true
+            };
+            // Push remaining rows to stream
+            this.pushBufferedRows(this.chunkBuffer);
+            // Call chunk callback
+            const rows = this.chunkBuffer;
+            this.chunkBuffer = [];
+            this.invokeChunkCallback(rows, meta, callback);
+        }
+        else {
+            callback();
+        }
+    }
+    /**
+     * Reset info state for next row (used when skipping rows or after processing)
+     */
+    processBuffer(callback) {
+        const { skipEmptyLines = false, skipLines = 0 } = this.options;
+        const shouldSkipEmpty = skipEmptyLines;
+        // ==========================================================================
+        // Fast Mode: Skip quote detection, split directly by delimiter
+        // ==========================================================================
+        if (this.parseConfig.fastMode) {
+            this.processBufferFastMode(callback, shouldSkipEmpty);
+            return;
+        }
+        // ==========================================================================
+        // Standard Mode: Full RFC 4180 compliant parsing with quote handling
+        // Uses Scanner for efficient indexOf-based batch scanning
+        // ==========================================================================
+        const pendingRows = [];
+        // Feed current buffer to scanner (scanner accumulates data internally)
+        // The scanner maintains its own internal position tracking
+        this.scanner.feed(this.buffer);
+        this.buffer = ""; // Clear our buffer since scanner now owns the data
+        // Process complete rows from scanner
+        let scanResult;
+        while ((scanResult = this.scanner.nextRow()) !== null) {
+            // Always pass raw so _handleParsedRow can count newlines for accurate lineNumber
+            const rawRow = scanResult.raw;
+            const rowCharLength = (scanResult.raw?.length ?? 0) + (scanResult.newline?.length ?? 0);
+            // Apply trim to fields.
+            // Note: scanResult.fields is reused by the streaming scanner; we must copy even when trim is identity.
+            const row = this.parseConfig.trimFieldIsIdentity
+                ? scanResult.fields.slice()
+                : scanResult.fields.map(this.parseConfig.trimField);
+            const action = this._handleParsedRow({
+                fields: row,
+                charLength: rowCharLength,
+                raw: rawRow,
+                quoted: scanResult.quoted,
+                pendingRows,
+                shouldSkipEmpty,
+                skipLines,
+                callback
+            });
+            if (action === "stop") {
+                return;
+            }
+            if (action === "error") {
+                return;
+            }
+            // "continue" and "skip" both fall through to process next row
+        }
+        // Scanner internally tracks unconsumed data - no need to reset
+        // It will continue from where it left off on the next feed()
+        this.processPendingRows(pendingRows, callback);
+    }
+    getFastModeCompleteDataEnd(buffer) {
+        const { linebreakRegex } = this.parseConfig;
+        if (typeof linebreakRegex === "string") {
+            const sep = linebreakRegex;
+            if (sep === "") {
+                return -1;
+            }
+            const maxStart = buffer.length - sep.length;
+            if (maxStart < 0) {
+                return -1;
+            }
+            const idx = buffer.lastIndexOf(sep, maxStart);
+            if (idx === -1) {
+                return -1;
+            }
+            return idx + sep.length;
+        }
+        // Fast path for default newline detection with CRLF chunk-boundary handling.
+        if (linebreakRegex === DEFAULT_LINEBREAK_REGEX) {
+            const lastLF = buffer.lastIndexOf("\n");
+            const lastCR = buffer.lastIndexOf("\r");
+            let lastNewlineIndex;
+            if (lastCR > lastLF) {
+                // CR comes after LF - check if this is part of a CRLF at end of buffer.
+                // If \r is the last char, we need to wait for more data to see if \n follows.
+                if (lastCR === buffer.length - 1) {
+                    lastNewlineIndex = lastLF;
+                }
+                else {
+                    lastNewlineIndex = lastCR;
+                }
+            }
+            else {
+                lastNewlineIndex = lastLF;
+            }
+            if (lastNewlineIndex === -1) {
+                return -1;
+            }
+            return lastNewlineIndex + 1;
+        }
+        const re = new RegExp(linebreakRegex.source, `${linebreakRegex.flags}g`);
+        let lastEnd = -1;
+        for (let match = re.exec(buffer); match; match = re.exec(buffer)) {
+            lastEnd = match.index + match[0].length;
+            // Safety: avoid infinite loops for zero-length matches.
+            if (match[0].length === 0) {
+                re.lastIndex++;
+            }
+        }
+        return lastEnd;
+    }
+    /**
+     * Fast mode buffer processing - skips quote detection, splits directly by delimiter
+     */
+    processBufferFastMode(callback, shouldSkipEmpty) {
+        const { skipLines = 0 } = this.options;
+        const pendingRows = [];
+        const completeEnd = this.getFastModeCompleteDataEnd(this.buffer);
+        // If no complete line, wait for more data
+        if (completeEnd === -1) {
+            callback();
+            return;
+        }
+        // Process complete lines
+        const completeData = this.buffer.slice(0, completeEnd);
+        this.buffer = this.buffer.slice(completeEnd);
+        for (const { line, lineLengthWithEnding: lineCharLength } of splitLinesWithEndings(completeData, this.parseConfig.linebreakRegex)) {
+            // FastMode: skip empty lines early before split (optimization)
+            if (line === "" && shouldSkipEmpty) {
+                this.parseState.lineNumber++;
+                this.totalCharsProcessed += lineCharLength;
+                continue;
+            }
+            // Split by delimiter (fast path - no quote detection)
+            const row = line.split(this.parseConfig.delimiter);
+            const trimmedRow = this.parseConfig.trimFieldIsIdentity
+                ? row
+                : row.map(this.parseConfig.trimField);
+            // In fast mode, no fields are quoted
+            const quoted = this.parseConfig.infoOption ? getUnquotedArray(trimmedRow.length) : undefined;
+            const action = this._handleParsedRow({
+                fields: trimmedRow,
+                charLength: lineCharLength,
+                raw: line,
+                quoted,
+                pendingRows,
+                shouldSkipEmpty,
+                skipLines,
+                callback
+            });
+            if (action === "stop") {
+                return;
+            }
+            if (action === "error") {
+                return;
+            }
+        }
+        this.processPendingRows(pendingRows, callback);
+    }
+    buildRow(rawRow, info) {
+        const { dynamicTyping, castDate, groupColumnsByName = false } = this.options;
+        let record;
+        if (this.options.headers && this.parseState.headerRow) {
+            // Use shared utility for row-to-object conversion
+            const obj = convertRowToObject(rawRow, this.parseState.headerRow, this.parseState.originalHeaders, groupColumnsByName);
+            // Apply dynamicTyping and/or castDate if configured
+            if (dynamicTyping || castDate) {
+                record = applyDynamicTypingToRow(obj, dynamicTyping || false, castDate);
+            }
+            else {
+                record = obj;
+            }
+        }
+        else {
+            // Array mode
+            if (dynamicTyping || castDate) {
+                // For array mode, can only use dynamicTyping: true (all columns)
+                // or per-column config if we happen to have headers
+                record = applyDynamicTypingToArrayRow(rawRow, this.parseState.headerRow ? filterValidHeaders(this.parseState.headerRow) : null, dynamicTyping || false, castDate);
+            }
+            else {
+                record = rawRow;
+            }
+        }
+        // Wrap with info if info option is enabled
+        if (this.parseConfig.infoOption) {
+            if (!info) {
+                // Should not happen: parse-core provides info when infoOption is enabled.
+                const fallback = {
+                    index: 0,
+                    line: this.parseState.currentRowStartLine,
+                    offset: this.parseState.currentRowStartOffset,
+                    quoted: [...this.parseState.currentRowQuoted],
+                    raw: this.parseConfig.rawOption ? this.parseState.currentRawRow : undefined
+                };
+                info = fallback;
+            }
+            // Use unknown cast - when info: true, Row type is extended to RecordWithInfo
+            return { record, info };
+        }
+        return record;
+    }
+    /**
+     * Shared per-row handling for all four processing paths (processBuffer, processBufferFastMode,
+     * flushCurrentRow, flushFastModeRemainder).
+     *
+     * Performs: lineNumber increment, toLine/skipLines checks, info tracking, maxRowBytes,
+     * raw row assignment, shouldSkipRow, and processCompletedRow delegation.
+     *
+     * @returns "continue" — row processed, keep going
+     *          "skip"     — row skipped, keep going
+     *          "stop"     — toLine/maxRows reached; pendingRows already flushed via callback
+     *          "error"    — error passed to callback
+     */
+    _handleParsedRow(input) {
+        const { fields, charLength, raw, quoted, pendingRows, shouldSkipEmpty, skipLines, callback } = input;
+        // Save the start line BEFORE counting newlines (for accurate info.line on multi-line rows)
+        const rowStartLine = this.parseState.lineNumber + 1;
+        // Update line number (count newlines in raw content for multi-line quoted fields)
+        if (raw !== undefined) {
+            let newlines = 1;
+            for (let i = 0; i < raw.length; i++) {
+                const ch = raw.charCodeAt(i);
+                if (ch === 10) {
+                    newlines++;
+                }
+                else if (ch === 13) {
+                    if (i + 1 < raw.length && raw.charCodeAt(i + 1) === 10) {
+                        i++;
+                    }
+                    newlines++;
+                }
+            }
+            this.parseState.lineNumber += newlines;
+        }
+        else {
+            this.parseState.lineNumber++;
+        }
+        // Check toLine - stop parsing at specified line number
+        const { toLine } = this.options;
+        if (toLine !== undefined && this.parseState.lineNumber > toLine) {
+            this.toLineReached = true;
+            this.totalCharsProcessed += charLength;
+            this.processPendingRows(pendingRows, callback);
+            return "stop";
+        }
+        // Skip lines at beginning
+        if (this.parseState.lineNumber <= skipLines) {
+            this.totalCharsProcessed += charLength;
+            return "skip";
+        }
+        // Set up info tracking state
+        if (this.parseConfig.infoOption) {
+            this.parseState.currentRowStartLine = rowStartLine;
+            this.parseState.currentRowStartOffset = this.totalCharsProcessed;
+            if (quoted) {
+                this.parseState.currentRowQuoted = quoted;
+            }
+        }
+        // Update char offset (RecordInfo.offset is character offset)
+        this.totalCharsProcessed += charLength;
+        // Check maxRowBytes limit
+        if (raw !== undefined && this.parseConfig.maxRowBytes !== undefined) {
+            const rawBytes = getUtf8ByteLength(raw);
+            if (rawBytes > this.parseConfig.maxRowBytes) {
+                callback(new Error(`Row exceeds the maximum size of ${this.parseConfig.maxRowBytes} bytes`));
+                return "error";
+            }
+        }
+        // Set raw row for info tracking
+        if (this.parseConfig.rawOption && raw !== undefined) {
+            this.parseState.currentRawRow = raw;
+        }
+        // Skip comment/empty lines
+        if (this.shouldSkipRow(fields, shouldSkipEmpty)) {
+            return "skip";
+        }
+        // Process completed row (handles headers, skipRows, column validation, maxRows)
+        if (!this.processCompletedRow(fields, pendingRows)) {
+            this.processPendingRows(pendingRows, callback);
+            return "stop";
+        }
+        return "continue";
+    }
+    /**
+     * Process a completed row (shared logic for standard and fast mode)
+     * Returns true if processing should continue, false if maxRows/toLine reached
+     */
+    processCompletedRow(row, pendingRows) {
+        // State is now unified via accessors - no manual sync needed
+        const result = processCompletedRowCore(row, this.parseState, this.parseConfig, this.parseErrorsSink, this.parseState.lineNumber);
+        // Clear sink to prevent unbounded memory growth.
+        // Errors are reported via result.reason (data-invalid) or onSkip callback;
+        // the sink is only used as a shared collector for processCompletedRowCore.
+        this.parseErrorsSink.length = 0;
+        // Emit headers event when headers become available
+        this.emitHeaders();
+        // Column mismatch reporting (stream API) - emit event when reason is provided
+        if (result.reason) {
+            this.emit("data-invalid", row, result.reason);
+        }
+        if (result.stop) {
+            return false;
+        }
+        if (result.skipped) {
+            return true;
+        }
+        if (result.row) {
+            const builtRow = this.buildRow(result.row, result.info);
+            // Attach extras to the record for columnMismatch.more: 'keep' (consistent with sync parser)
+            if (result.extras && result.extras.length > 0) {
+                const record = this.parseConfig.infoOption ? builtRow.record : builtRow;
+                record._extra = result.extras;
+            }
+            pendingRows.push(builtRow);
+        }
+        return true;
+    }
+    emitHeaders() {
+        if (!this.headersEmitted && this.parseState.headerRow) {
+            this.headersEmitted = true;
+            this.emit("headers", filterValidHeaders(this.parseState.headerRow));
+        }
+    }
+    /**
+     * Check if a line should be skipped (comment or empty)
+     */
+    shouldSkipRow(row, shouldSkipEmpty) {
+        // Delegate to parse-core to keep sync/stream behavior aligned.
+        // Note: row passed here is already split into fields.
+        return shouldSkipRowCore(row, this.parseConfig.comment, shouldSkipEmpty, false // skipRecordsWithEmptyValues is handled inside processCompletedRowCore
+        );
+    }
+    processPendingRows(rows, callback) {
+        if (rows.length === 0) {
+            callback();
+            return;
+        }
+        // If chunk callback aborted, skip processing
+        if (this.chunkAborted) {
+            callback();
+            return;
+        }
+        // Fast path: no transform or validate, push all rows directly
+        if (!this._rowTransform && !this._rowValidator) {
+            let index = 0;
+            const processNextBatch = () => {
+                while (index < rows.length && !this.chunkAborted) {
+                    const row = rows[index++];
+                    if (this.options.chunk) {
+                        // Collect rows for chunk callback
+                        this.chunkBuffer.push(row);
+                        this.totalRowsProcessed++;
+                        // Check if chunk is full
+                        if (this.chunkBuffer.length >= this.chunkSize) {
+                            this.flushChunk(err => {
+                                if (err) {
+                                    callback(err);
+                                    return;
+                                }
+                                // If chunk callback aborted, stop processing
+                                if (this.chunkAborted) {
+                                    callback();
+                                    return;
+                                }
+                                // Trampoline: yield to event loop periodically to prevent stack overflow
+                                if (index % 1000 === 0) {
+                                    setTimeout(processNextBatch, 0);
+                                }
+                                else {
+                                    processNextBatch();
+                                }
+                            });
+                            return;
+                        }
+                    }
+                    else {
+                        // No chunk callback, push directly with backpressure support
+                        const canContinue = this.pushRow(row);
+                        if (!canContinue) {
+                            // Backpressure applied - pause and wait for _read()
+                            this.backpressure = true;
+                            this.pendingCallback = () => processNextBatch();
+                            return;
+                        }
+                    }
+                }
+                callback();
+            };
+            processNextBatch();
+            return;
+        }
+        // Slow path: process rows one by one with transform/validate
+        let index = 0;
+        const processNext = () => {
+            if (index >= rows.length) {
+                callback();
+                return;
+            }
+            const row = rows[index++];
+            this.transformAndValidateRow(row, (err, result) => {
+                if (err) {
+                    callback(err);
+                    return;
+                }
+                if (result && result.isValid && result.row !== null) {
+                    if (this.options.chunk) {
+                        // Collect rows for chunk callback
+                        this.chunkBuffer.push(result.row);
+                        this.totalRowsProcessed++;
+                        // Check if chunk is full
+                        if (this.chunkBuffer.length >= this.chunkSize) {
+                            this.flushChunk(err2 => {
+                                if (err2) {
+                                    callback(err2);
+                                    return;
+                                }
+                                // Continue processing after chunk flush
+                                if (index % 1000 === 0) {
+                                    setTimeout(processNext, 0);
+                                }
+                                else {
+                                    processNext();
+                                }
+                            });
+                            return;
+                        }
+                    }
+                    else {
+                        // No chunk callback, push directly with backpressure support
+                        const canContinue = this.pushRow(result.row);
+                        if (!canContinue) {
+                            // Backpressure applied - pause and wait for _read()
+                            this.backpressure = true;
+                            this.pendingCallback = () => processNext();
+                            return;
+                        }
+                    }
+                }
+                else if (result && !result.isValid) {
+                    this.emit("data-invalid", result.row, result.reason);
+                }
+                // Use setTimeout to prevent stack overflow for large datasets
+                if (index % 1000 === 0) {
+                    setTimeout(processNext, 0);
+                }
+                else {
+                    processNext();
+                }
+            });
+        };
+        processNext();
+    }
+    /**
+     * Flush the current chunk buffer to the chunk callback
+     */
+    flushChunk(callback) {
+        if (this.chunkBuffer.length === 0 || !this.options.chunk) {
+            callback();
+            return;
+        }
+        const chunkRowCount = this.chunkBuffer.length;
+        const cursor = this.totalRowsProcessed - chunkRowCount;
+        const meta = {
+            cursor,
+            rowCount: chunkRowCount,
+            isFirstChunk: this.isFirstChunk,
+            isLastChunk: false
+        };
+        this.isFirstChunk = false;
+        // Take rows and clear buffer before callback
+        const rows = this.chunkBuffer;
+        this.chunkBuffer = [];
+        // Push rows to stream, then invoke callback
+        this.pushBufferedRows(rows);
+        this.invokeChunkCallback(rows, meta, callback);
+    }
+    transformAndValidateRow(row, callback) {
+        // First apply transform
+        if (this._rowTransform) {
+            this._rowTransform(row, (transformErr, transformedRow) => {
+                if (transformErr) {
+                    callback(transformErr);
+                    return;
+                }
+                if (transformedRow === null || transformedRow === undefined) {
+                    callback(null, { row: null, isValid: true });
+                    return;
+                }
+                // Then validate
+                this.validateRow(transformedRow, callback);
+            });
+        }
+        else {
+            this.validateRow(row, callback);
+        }
+    }
+    validateRow(row, callback) {
+        if (this._rowValidator) {
+            this._rowValidator(row, (validateErr, isValid, reason) => {
+                if (validateErr) {
+                    callback(validateErr);
+                    return;
+                }
+                callback(null, { row, isValid: isValid ?? false, reason });
+            });
+        }
+        else {
+            callback(null, { row, isValid: true });
+        }
+    }
+}
+/**
+ * Create parser stream factory
+ */
+export function createCsvParserStream(options = {}) {
+    return new CsvParserStream(options);
+}