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

package/dist/browser/modules/csv/parse/async.js

@@ -0,0 +1,288 @@
+/**
+ * Async CSV Parser
+ *
+ * Provides async CSV parsing supporting:
+ * - String input (delegates to sync parser)
+ * - AsyncIterable<string|Uint8Array> inputs
+ * - ReadableStream inputs (WHATWG streams)
+ *
+ * API Semantics:
+ * - parseCsvAsync(): Collects all rows into memory, returns full CsvParseResult.
+ *   Best for small-to-medium files where you need complete data at once.
+ *
+ * - parseCsvRows(): True streaming async generator that yields rows one at a time.
+ *   Best for large files or when processing rows incrementally.
+ *   Memory-efficient as it doesn't buffer the entire result.
+ *
+ * Note: Both functions are async but have different memory characteristics.
+ * parseCsvAsync buffers the entire input; parseCsvRows streams progressively.
+ */
+import { parseCsv } from "./sync.js";
+import { CsvParserStream } from "../stream/parser.js";
+import { getUtf8ByteLength } from "../constants.js";
+import { CsvError } from "../errors.js";
+import { isReadableStreamLike, readableStreamToAsyncIterable } from "../../stream/utils.base.js";
+function isAsyncIterable(value) {
+    return Boolean(value && typeof value[Symbol.asyncIterator] === "function");
+}
+function normalizeAsyncInput(input) {
+    if (isAsyncIterable(input)) {
+        return input;
+    }
+    if (isReadableStreamLike(input)) {
+        return readableStreamToAsyncIterable(input);
+    }
+    throw new TypeError("input must be an AsyncIterable or a ReadableStream");
+}
+/**
+ * Collect AsyncIterable<string|Uint8Array> to a complete string.
+ * Unified helper for both collectAsyncInput and parseCsvWithProgress.
+ *
+ * @param input - Async iterable of chunks
+ * @param encoding - Text encoding (default: utf-8)
+ * @param onChunk - Optional callback for each chunk (for progress reporting)
+ */
+async function collectText(input, encoding, onChunk) {
+    const chunks = [];
+    const decoder = new TextDecoder(encoding || "utf-8");
+    let totalBytes = 0;
+    for await (const chunk of input) {
+        if (typeof chunk === "string") {
+            chunks.push(chunk);
+            // Always track bytes for consistent semantics
+            totalBytes += getUtf8ByteLength(chunk);
+        }
+        else {
+            chunks.push(decoder.decode(chunk, { stream: true }));
+            totalBytes += chunk.length;
+        }
+        if (onChunk) {
+            onChunk(totalBytes);
+        }
+    }
+    // Flush decoder
+    const final = decoder.decode();
+    if (final) {
+        chunks.push(final);
+    }
+    return { content: chunks.join(""), totalBytes };
+}
+/**
+ * Parse CSV asynchronously (implementation).
+ */
+export async function parseCsvAsync(input, options = {}) {
+    // If input is a string, use sync parser directly
+    if (typeof input === "string") {
+        return parseCsv(input, options);
+    }
+    const asyncInput = normalizeAsyncInput(input);
+    const { content } = await collectText(asyncInput, options.encoding);
+    return parseCsv(content, options);
+}
+/**
+ * Parse CSV as an async generator, yielding rows as they are parsed.
+ * This is the true streaming version that yields rows one at a time.
+ *
+ * @example
+ * ```ts
+ * // Process large file row by row
+ * for await (const row of parseCsvRows(fileStream, { headers: true })) {
+ *   console.log(row);
+ * }
+ *
+ * // With validation
+ * for await (const row of parseCsvRows(input, {
+ *   headers: true,
+ *   validate: (row) => row.id !== ""
+ * })) {
+ *   // Only valid rows
+ * }
+ * ```
+ */
+export async function* parseCsvRows(input, options = {}) {
+    // objname produces a map output in the sync parser, which cannot be produced
+    // in a true streaming fashion. Fall back to buffered parsing.
+    if (options.objname) {
+        let content;
+        try {
+            content =
+                typeof input === "string"
+                    ? input
+                    : (await collectText(normalizeAsyncInput(input), options.encoding)).content;
+        }
+        catch (error) {
+            throw new CsvError("Failed to read input for objname parsing", { cause: error });
+        }
+        let result;
+        try {
+            result = parseCsv(content, options);
+        }
+        catch (error) {
+            throw new CsvError("Failed to parse CSV with objname option", { cause: error });
+        }
+        if (Array.isArray(result)) {
+            for (const row of result) {
+                yield row;
+            }
+            return;
+        }
+        const rowsValue = result.rows;
+        if (Array.isArray(rowsValue)) {
+            for (const row of rowsValue) {
+                yield row;
+            }
+            return;
+        }
+        if (rowsValue && typeof rowsValue === "object") {
+            for (const row of Object.values(rowsValue)) {
+                yield row;
+            }
+        }
+        return;
+    }
+    const parser = new CsvParserStream(options);
+    const queue = [];
+    let pendingResolve = null;
+    let ended = false;
+    let streamError = null;
+    let aborted = false;
+    const pushEvent = (ev) => {
+        if (pendingResolve) {
+            const resolve = pendingResolve;
+            pendingResolve = null;
+            resolve(ev);
+            return;
+        }
+        queue.push(ev);
+    };
+    const onData = (value) => {
+        pushEvent({ type: "data", value });
+    };
+    const onEnd = () => {
+        ended = true;
+        pushEvent({ type: "end" });
+    };
+    const onError = (error) => {
+        streamError = error;
+        pushEvent({ type: "error", error });
+    };
+    parser.on("data", onData);
+    parser.once("end", onEnd);
+    parser.once("error", onError);
+    const writePromise = (async () => {
+        try {
+            if (typeof input === "string") {
+                parser.end(input);
+                return;
+            }
+            const asyncInput = normalizeAsyncInput(input);
+            for await (const chunk of asyncInput) {
+                if (aborted) {
+                    break;
+                }
+                const canContinue = parser.write(chunk);
+                if (!canContinue && !aborted) {
+                    await new Promise(resolve => parser.once("drain", resolve));
+                }
+            }
+            if (!aborted) {
+                parser.end();
+            }
+            else {
+                parser.destroy();
+            }
+        }
+        catch (e) {
+            parser.destroy(e);
+        }
+    })();
+    try {
+        while (true) {
+            if (queue.length > 0) {
+                const ev = queue.shift();
+                if (ev.type === "data") {
+                    yield ev.value;
+                    continue;
+                }
+                if (ev.type === "error") {
+                    throw ev.error;
+                }
+                // end
+                break;
+            }
+            if (streamError) {
+                throw streamError;
+            }
+            if (ended) {
+                break;
+            }
+            const ev = await new Promise(resolve => {
+                pendingResolve = resolve;
+            });
+            if (ev.type === "data") {
+                yield ev.value;
+            }
+            else if (ev.type === "error") {
+                throw ev.error;
+            }
+            else {
+                break;
+            }
+        }
+    }
+    finally {
+        aborted = true;
+        // Ensure stream stops as soon as possible.
+        parser.destroy();
+        // Release the writer if it is waiting for drain (destroy does not emit drain).
+        parser.emit("drain");
+        parser.off("data", onData);
+        parser.off("end", onEnd);
+        parser.off("error", onError);
+        // Avoid unhandled rejections from the writer task.
+        await writePromise.catch(() => undefined);
+    }
+}
+/**
+ * Parse CSV with progress callback for large files.
+ *
+ * @param input - CSV string or async iterable
+ * @param options - Parse options
+ * @param onProgress - Called periodically with progress info
+ */
+export async function parseCsvWithProgress(input, options = {}, onProgress) {
+    // Collect input and track bytes
+    let content;
+    let totalBytes;
+    if (typeof input === "string") {
+        content = input;
+        totalBytes = getUtf8ByteLength(content);
+    }
+    else {
+        const asyncInput = normalizeAsyncInput(input);
+        const result = await collectText(asyncInput, options.encoding, onProgress ? bytes => onProgress({ rowsProcessed: 0, bytesProcessed: bytes }) : undefined);
+        content = result.content;
+        totalBytes = result.totalBytes;
+    }
+    // Parse
+    const result = parseCsv(content, options);
+    // Report final progress
+    if (onProgress) {
+        let rowCount;
+        if (Array.isArray(result)) {
+            rowCount = result.length;
+        }
+        else if (typeof result.rows === "object" && !Array.isArray(result.rows)) {
+            // objname mode: rows is a plain object
+            rowCount = Object.keys(result.rows).length;
+        }
+        else if (Array.isArray(result.rows)) {
+            rowCount = result.rows.length;
+        }
+        else {
+            rowCount = 0;
+        }
+        onProgress({ rowsProcessed: rowCount, bytesProcessed: totalBytes });
+    }
+    return result;
+}

package/dist/browser/modules/csv/parse/config.d.ts

@@ -0,0 +1,100 @@
+/**
+ * CSV Parse Configuration
+ *
+ * Defines the ParseConfig type and factory function for creating
+ * normalized parsing configuration from user options.
+ */
+import type { CsvParseOptions } from "../types.js";
+import { createOnSkipHandler } from "./helpers.js";
+import type { ScannerConfig } from "./scanner/index.js";
+/**
+ * Resolved parsing configuration (after option normalization)
+ */
+export interface ParseConfig {
+    delimiter: string;
+    linebreak: string;
+    /** Pre-compiled regex for line splitting (used in fast mode) */
+    linebreakRegex: RegExp | string;
+    quote: string;
+    escape: string;
+    quoteEnabled: boolean;
+    trimField: (s: string) => string;
+    /** Whether trimField is an identity function (no actual trimming) - cached for performance */
+    trimFieldIsIdentity: boolean;
+    shouldSkipEmpty: boolean | "greedy";
+    skipLines: number;
+    skipRows: number;
+    maxRows?: number;
+    toLine?: number;
+    maxRowBytes?: number;
+    comment?: string;
+    fastMode: boolean;
+    relaxQuotes: boolean;
+    columnLess: "error" | "pad";
+    columnMore: "error" | "truncate" | "keep";
+    groupColumnsByName: boolean;
+    skipRecordsWithError: boolean;
+    skipRecordsWithEmptyValues: boolean;
+    infoOption: boolean;
+    rawOption: boolean;
+    dynamicTyping: CsvParseOptions["dynamicTyping"];
+    castDate: CsvParseOptions["castDate"];
+    invokeOnSkip: ReturnType<typeof createOnSkipHandler>;
+    headers: CsvParseOptions["headers"];
+}
+/**
+ * Options for creating ParseConfig.
+ * - For batch parsing: provide `input` for auto-detection and BOM stripping
+ * - For streaming: omit `input` (will use defaults, detection handled separately)
+ */
+export interface CreateParseConfigOptions {
+    /** Raw input string (for batch parsing with auto-detection) */
+    input?: string;
+    /** CSV parse options */
+    options: CsvParseOptions;
+    /** Override delimiter (for streaming after detection) */
+    detectedDelimiter?: string;
+}
+/**
+ * Result of createParseConfig
+ */
+export interface ParseConfigResult {
+    /** Resolved parse configuration */
+    config: ParseConfig;
+    /** Processed input with BOM stripped and beforeFirstChunk applied (if input was provided) */
+    processedInput?: string;
+}
+/**
+ * Create a normalized ParseConfig from options.
+ * This is the single source of truth for configuration normalization,
+ * used by both sync and streaming parsers.
+ *
+ * @example Batch parsing
+ * ```ts
+ * const { config, processedInput } = createParseConfig({ input: csvString, options });
+ * ```
+ *
+ * @example Streaming parsing
+ * ```ts
+ * const { config } = createParseConfig({ options });
+ * // Later, after delimiter detection:
+ * config.delimiter = detectedDelimiter;
+ * ```
+ */
+export declare function createParseConfig(opts: CreateParseConfigOptions): ParseConfigResult;
+/**
+ * Resolve options into a normalized config object.
+ * Convenience wrapper around createParseConfig that ensures processedInput is non-null.
+ */
+export declare function resolveParseConfig(input: string, options: CsvParseOptions): {
+    config: ParseConfig;
+    processedInput: string;
+};
+/**
+ * Convert ParseConfig to ScannerConfig
+ */
+export declare function toScannerConfig(config: ParseConfig): ScannerConfig;
+/**
+ * Create a trim function based on options
+ */
+export declare function makeTrimField(trim: boolean, ltrim: boolean, rtrim: boolean): (s: string) => string;

package/dist/browser/modules/csv/parse/config.js

@@ -0,0 +1,159 @@
+/**
+ * CSV Parse Configuration
+ *
+ * Defines the ParseConfig type and factory function for creating
+ * normalized parsing configuration from user options.
+ */
+import { createOnSkipHandler } from "./helpers.js";
+import { normalizeQuoteOption, normalizeEscapeOption, detectDelimiter, detectLinebreak, stripBom } from "../utils/detect.js";
+import { DEFAULT_LINEBREAK_REGEX } from "../constants.js";
+import { CsvError } from "../errors.js";
+// =============================================================================
+// Configuration Factory
+// =============================================================================
+/**
+ * Create a normalized ParseConfig from options.
+ * This is the single source of truth for configuration normalization,
+ * used by both sync and streaming parsers.
+ *
+ * @example Batch parsing
+ * ```ts
+ * const { config, processedInput } = createParseConfig({ input: csvString, options });
+ * ```
+ *
+ * @example Streaming parsing
+ * ```ts
+ * const { config } = createParseConfig({ options });
+ * // Later, after delimiter detection:
+ * config.delimiter = detectedDelimiter;
+ * ```
+ */
+export function createParseConfig(opts) {
+    const { input, options, detectedDelimiter } = opts;
+    const { delimiter: delimiterOption = ",", delimitersToGuess, lineEnding: lineEndingOption = "", quote: quoteOption = '"', escape: escapeOption, skipEmptyLines = false, trim = false, ltrim = false, rtrim = false, headers = false, comment, maxRows, toLine, skipLines = 0, skipRows = 0, columnMismatch, groupColumnsByName = false, fastMode = false, dynamicTyping, castDate, beforeFirstChunk, info: infoOption = false, raw: rawOption = false, relaxQuotes = false, skipRecordsWithError = false, skipRecordsWithEmptyValues = false, onSkip, maxRowBytes } = options;
+    // Column mismatch defaults to strict (error on any mismatch)
+    const columnLess = columnMismatch?.less ?? "error";
+    const columnMore = columnMismatch?.more ?? "error";
+    // Process input if provided (batch mode)
+    let processedInput;
+    if (input !== undefined) {
+        processedInput = input;
+        // Apply beforeFirstChunk if provided
+        if (beforeFirstChunk) {
+            const result = beforeFirstChunk(processedInput);
+            if (typeof result === "string") {
+                processedInput = result;
+            }
+            else if (result !== undefined && result !== null) {
+                // Validate return type - must be string or void/undefined
+                throw new CsvError(`beforeFirstChunk must return a string or undefined, got ${typeof result}`);
+            }
+        }
+        // Strip BOM
+        processedInput = stripBom(processedInput);
+    }
+    const shouldSkipEmpty = skipEmptyLines;
+    // Normalize quote/escape
+    const { enabled: quoteEnabled, char: quote } = normalizeQuoteOption(quoteOption);
+    const escapeNormalized = normalizeEscapeOption(escapeOption, quote);
+    const escape = escapeNormalized.enabled ? escapeNormalized.char || quote : "";
+    // Determine delimiter
+    let delimiter;
+    if (detectedDelimiter !== undefined) {
+        // Use externally detected delimiter (streaming mode)
+        delimiter = detectedDelimiter;
+    }
+    else if (delimiterOption === "" && processedInput !== undefined) {
+        // Auto-detect from input (batch mode)
+        delimiter = detectDelimiter(processedInput, quote || '"', delimitersToGuess, comment, shouldSkipEmpty);
+    }
+    else if (delimiterOption === "") {
+        // Streaming mode with auto-detect - use default, will be updated later
+        delimiter = ",";
+    }
+    else {
+        delimiter = delimiterOption;
+    }
+    // Determine linebreak
+    const linebreak = lineEndingOption || (processedInput !== undefined ? detectLinebreak(processedInput) : "\n");
+    // Pre-compile linebreak regex for fast mode
+    const linebreakRegex = linebreak && linebreak !== "\n" && linebreak !== "\r\n" && linebreak !== "\r"
+        ? linebreak
+        : DEFAULT_LINEBREAK_REGEX;
+    const config = {
+        delimiter,
+        linebreak,
+        linebreakRegex,
+        quote,
+        escape,
+        quoteEnabled,
+        trimField: makeTrimField(trim, ltrim, rtrim),
+        // Cache whether trimField is identity to avoid per-row checking
+        trimFieldIsIdentity: !trim && !ltrim && !rtrim,
+        shouldSkipEmpty,
+        skipLines,
+        skipRows,
+        maxRows,
+        toLine,
+        maxRowBytes,
+        comment,
+        fastMode,
+        relaxQuotes,
+        columnLess,
+        columnMore,
+        groupColumnsByName,
+        skipRecordsWithError,
+        skipRecordsWithEmptyValues,
+        infoOption,
+        rawOption,
+        dynamicTyping,
+        castDate,
+        invokeOnSkip: createOnSkipHandler(onSkip),
+        headers
+    };
+    return { config, processedInput };
+}
+/**
+ * Resolve options into a normalized config object.
+ * Convenience wrapper around createParseConfig that ensures processedInput is non-null.
+ */
+export function resolveParseConfig(input, options) {
+    const result = createParseConfig({ input, options });
+    return {
+        config: result.config,
+        processedInput: result.processedInput
+    };
+}
+// =============================================================================
+// Scanner Config Helper
+// =============================================================================
+/**
+ * Convert ParseConfig to ScannerConfig
+ */
+export function toScannerConfig(config) {
+    return {
+        delimiter: config.delimiter,
+        quote: config.quote,
+        escape: config.escape,
+        quoteEnabled: config.quoteEnabled,
+        relaxQuotes: config.relaxQuotes
+    };
+}
+// =============================================================================
+// Trim Function Factory
+// =============================================================================
+/**
+ * Create a trim function based on options
+ */
+export function makeTrimField(trim, ltrim, rtrim) {
+    if (trim || (ltrim && rtrim)) {
+        return (s) => s.trim();
+    }
+    if (ltrim) {
+        return (s) => s.trimStart();
+    }
+    if (rtrim) {
+        return (s) => s.trimEnd();
+    }
+    return (s) => s;
+}

package/dist/browser/modules/csv/parse/helpers.d.ts

@@ -0,0 +1,114 @@
+/**
+ * CSV Parse Utilities
+ *
+ * Shared parsing helpers used by both sync (parseCsv) and streaming (CsvParserStream)
+ * parsers to ensure consistent behavior:
+ *
+ * - Header processing: Handle headers option (true/array/transform)
+ * - Column validation: Check row length against expected column count
+ * - Row-to-object conversion: Transform string[] to Record<string, any>
+ * - Dynamic typing: Apply type coercion based on configuration
+ *
+ * These utilities are extracted to avoid code duplication between
+ * the batch parser (parse.ts) and the streaming parser (csv-stream.ts).
+ */
+import { type HeaderArray } from "../utils/row.js";
+import type { CsvRecordError, OnSkipCallback } from "../types.js";
+/**
+ * Options for header processing
+ */
+interface HeaderProcessOptions {
+    /** Headers configuration: true, array, or function */
+    headers: boolean | string[] | ((row: string[]) => (string | null | undefined)[]);
+    /** Whether to group columns by name (affects originalHeaders computation) */
+    groupColumnsByName?: boolean;
+}
+/**
+ * Options for column validation
+ */
+interface ColumnValidationOptions {
+    /** Strategy for rows with fewer columns than expected */
+    columnLess: "error" | "pad";
+    /** Strategy for rows with more columns than expected */
+    columnMore: "error" | "truncate" | "keep";
+}
+/**
+ * Column validation result
+ */
+interface ColumnValidationResult {
+    /** Whether the row is valid */
+    isValid: boolean;
+    /** Error code if invalid: 'TooManyFields' or 'TooFewFields' */
+    errorCode?: "TooManyFields" | "TooFewFields";
+    /** Error message if invalid */
+    reason?: string;
+    /** Whether the row was modified (padded or trimmed) */
+    modified: boolean;
+    /** Extra columns when columnMismatch.more is 'keep' */
+    extras?: string[];
+}
+/**
+ * Result of processing headers
+ */
+interface HeaderProcessResult {
+    /** The processed (deduplicated) headers */
+    headers: HeaderArray;
+    /** The original (non-deduplicated) headers, for groupColumnsByName support. Null when groupColumnsByName is false. */
+    originalHeaders: HeaderArray | null;
+    /** Map of renamed headers (new name -> original name) */
+    renamedHeaders: Record<string, string> | null;
+    /** Whether the current row should be skipped (was used as headers) */
+    skipCurrentRow: boolean;
+}
+/**
+ * Process headers from first row or configuration.
+ * Shared logic between parseCsv and CsvParserStream.
+ *
+ * @param row - The current row being processed
+ * @param options - Header processing options
+ * @param existingHeaders - Already configured headers (for array case)
+ * @returns Processing result or null if headers not applicable
+ */
+export declare function processHeaders(row: string[], options: HeaderProcessOptions, existingHeaders: HeaderArray | null): HeaderProcessResult | null;
+/**
+ * Validate and adjust row column count against expected headers.
+ * Shared logic between parseCsv and CsvParserStream.
+ *
+ * @param row - The row to validate (will be modified in place if needed)
+ * @param expectedCols - Expected number of columns (from headers)
+ * @param options - Validation options
+ * @returns Validation result
+ */
+export declare function validateAndAdjustColumns(row: string[], expectedCols: number, options: ColumnValidationOptions): ColumnValidationResult;
+/**
+ * Create a safe onSkip handler that catches errors from user callback.
+ *
+ * The onSkip callback is user-provided and may throw errors. We wrap it
+ * to prevent callback errors from interrupting parsing. Errors in the
+ * callback are silently ignored since there's no good way to surface them
+ * in the sync parsing context.
+ *
+ * For better error visibility in async/streaming contexts, consider
+ * emitting a warning event on the stream instead.
+ */
+export declare function createOnSkipHandler(onSkip: OnSkipCallback | undefined): ((error: CsvRecordError, record: string[] | null) => void) | null;
+/**
+ * Convert a row array to an object, optionally grouping duplicate column names.
+ * Unified function that handles both normal and grouped modes.
+ *
+ * @param row - The row values as an array
+ * @param headers - The deduplicated header names
+ * @param originalHeaders - The original (non-deduplicated) headers for grouping
+ * @param groupColumnsByName - Whether to group duplicate column names
+ * @returns Object with header keys and row values
+ */
+export declare function convertRowToObject(row: string[], headers: HeaderArray, originalHeaders: HeaderArray | null, groupColumnsByName: boolean): Record<string, string | string[]>;
+/**
+ * Filter out null/undefined values from a header array.
+ * Returns only the valid string headers.
+ *
+ * @param headers - Header array that may contain null/undefined values
+ * @returns Array of valid string headers (null/undefined removed)
+ */
+export declare function filterValidHeaders(headers: HeaderArray): string[];
+export {};