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

package/dist/browser/modules/csv/parse/scanner/types.d.ts

@@ -0,0 +1,185 @@
+/**
+ * CSV Scanner Types
+ *
+ * Type definitions for the high-performance CSV field scanner.
+ * The scanner uses indexOf-based batch scanning instead of character-by-character parsing.
+ */
+/**
+ * Scanner configuration options.
+ * These are the low-level options needed for field scanning.
+ */
+export interface ScannerConfig {
+    /** Field delimiter (supports multi-character, e.g., "||" or "\t\t") */
+    delimiter: string;
+    /** Quote character (single character, e.g., '"') */
+    quote: string;
+    /** Escape character (usually same as quote for RFC 4180, or backslash) */
+    escape: string;
+    /** Whether quoting is enabled */
+    quoteEnabled: boolean;
+    /** Allow unescaped quotes mid-field (relaxed parsing mode) */
+    relaxQuotes: boolean;
+}
+/**
+ * Default scanner configuration
+ */
+export declare const DEFAULT_SCANNER_CONFIG: ScannerConfig;
+/**
+ * Result of scanning a single field.
+ */
+export interface FieldScanResult {
+    /** The parsed field value (with quotes and escapes processed) */
+    value: string;
+    /** Whether the field was quoted */
+    quoted: boolean;
+    /** Position after the field (after delimiter or at line end) */
+    endPos: number;
+    /**
+     * Whether parsing is incomplete and needs more data.
+     * This happens when:
+     * - A quoted field is unterminated at buffer boundary
+     * - A CR is at the end of buffer (might be CRLF)
+     */
+    needMore: boolean;
+    /**
+     * For incomplete fields, the position to resume from.
+     * The caller should retain input[resumePos:] and prepend to next chunk.
+     */
+    resumePos?: number;
+    /** Whether the quoted field was unterminated (EOF inside quotes) */
+    unterminated?: boolean;
+}
+/**
+ * Result of scanning a complete row.
+ */
+export interface RowScanResult {
+    /** Parsed field values */
+    fields: string[];
+    /** Whether each field was quoted (same length as fields) */
+    quoted: boolean[];
+    /** Position after the row (after newline) */
+    endPos: number;
+    /** Whether the row is complete (ends with newline or EOF) */
+    complete: boolean;
+    /**
+     * Whether parsing needs more data.
+     * True when:
+     * - Row is incomplete (no newline found, not at EOF)
+     * - A quoted field spans buffer boundary
+     */
+    needMore: boolean;
+    /**
+     * Position to resume from when needMore is true.
+     * Data from this position should be retained for the next chunk.
+     */
+    resumePos?: number;
+    /** The actual newline sequence found ("\n", "\r\n", or "\r") */
+    newline?: string;
+    /** Whether there was an unterminated quoted field (EOF inside quotes) */
+    unterminatedQuote?: boolean;
+    /**
+     * Start position of the raw row in the input string.
+     * Used for zero-copy raw row extraction: `input.slice(rawStart, rawEnd)`.
+     */
+    rawStart: number;
+    /**
+     * End position of the raw row (excluding newline).
+     * Used for zero-copy raw row extraction: `input.slice(rawStart, rawEnd)`.
+     */
+    rawEnd: number;
+    /**
+     * The raw row string (original input without parsing).
+     * Only populated by streaming scanner's nextRow()/flush() methods.
+     * In sync mode, use input.slice(rawStart, rawEnd) instead.
+     */
+    raw?: string;
+}
+/**
+ * Internal state for streaming scanner.
+ * Note: The current implementation uses a simple buffer + position model.
+ * Complex cross-chunk state (partial fields, etc.) is handled by scanRow's resumePos.
+ */
+export interface ScannerState {
+    /** Buffered input data */
+    buffer: string;
+    /** Current position in buffer */
+    position: number;
+}
+/**
+ * Create initial scanner state.
+ */
+export declare function createScannerState(): ScannerState;
+/**
+ * High-performance CSV field scanner.
+ *
+ * The scanner provides two modes of operation:
+ * 1. **Sync mode**: Use `scanRow()` for complete input strings
+ * 2. **Streaming mode**: Use `feed()` + `nextRow()` for chunked input
+ *
+ * @example Sync mode
+ * ```ts
+ * const scanner = createScanner({ delimiter: "," });
+ * const result = scanner.scanRow('a,"b,c",d\n');
+ * // result.fields = ["a", "b,c", "d"]
+ * ```
+ *
+ * @example Streaming mode
+ * ```ts
+ * const scanner = createScanner({ delimiter: "," });
+ * scanner.feed('a,"b,c",d\ne,');  // First chunk
+ * const row1 = scanner.nextRow(); // { fields: ["a", "b,c", "d"], complete: true }
+ * scanner.feed('f,g\n');          // Second chunk
+ * const row2 = scanner.nextRow(); // { fields: ["e", "f", "g"], complete: true }
+ * ```
+ */
+export interface Scanner {
+    /** Current scanner configuration */
+    readonly config: ScannerConfig;
+    /**
+     * Scan a single row from input string.
+     *
+     * @param input - The input string to scan
+     * @param offset - Starting position (default: 0)
+     * @param isEof - Whether this is the end of input (default: false)
+     * @returns Scan result with fields and position info
+     */
+    scanRow(input: string, offset?: number, isEof?: boolean): RowScanResult;
+    /**
+     * Feed data into the streaming buffer.
+     *
+     * @param chunk - Data chunk to append to buffer
+     */
+    feed(chunk: string): void;
+    /**
+     * Get the next complete row from the buffer.
+     *
+     * **Important**: The returned `fields` and `quoted` arrays are reused internally
+     * for performance. If you need to store the result, copy the arrays:
+     * ```ts
+     * const result = scanner.nextRow();
+     * const fieldsCopy = [...result.fields];
+     * ```
+     *
+     * @returns Row result, or null if no complete row is available
+     */
+    nextRow(): RowScanResult | null;
+    /**
+     * Flush remaining data at end of input.
+     * Call this when there's no more data to feed.
+     *
+     * **Important**: The returned `fields` and `quoted` arrays are reused internally.
+     * Copy them if you need to store the result.
+     *
+     * @returns Final row result, or null if buffer is empty
+     */
+    flush(): RowScanResult | null;
+    /**
+     * Reset scanner state (for reuse).
+     */
+    reset(): void;
+    /**
+     * Get remaining buffered data.
+     * Useful for error recovery or debugging.
+     */
+    getBuffer(): string;
+}

package/dist/browser/modules/csv/parse/scanner/types.js

@@ -0,0 +1,25 @@
+/**
+ * CSV Scanner Types
+ *
+ * Type definitions for the high-performance CSV field scanner.
+ * The scanner uses indexOf-based batch scanning instead of character-by-character parsing.
+ */
+/**
+ * Default scanner configuration
+ */
+export const DEFAULT_SCANNER_CONFIG = {
+    delimiter: ",",
+    quote: '"',
+    escape: '"',
+    quoteEnabled: true,
+    relaxQuotes: false
+};
+/**
+ * Create initial scanner state.
+ */
+export function createScannerState() {
+    return {
+        buffer: "",
+        position: 0
+    };
+}

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

@@ -0,0 +1,46 @@
+/**
+ * CSV Parse State
+ *
+ * Defines the ParseState type and factory function for creating
+ * mutable parsing state. Also includes field building operations.
+ */
+import type { HeaderArray } from "../types.js";
+import type { ParseConfig } from "./config.js";
+/**
+ * Mutable parsing state - shared between sync and streaming parsers
+ */
+export interface ParseState {
+    lineNumber: number;
+    dataRowCount: number;
+    skippedDataRows: number;
+    truncated: boolean;
+    headerRow: HeaderArray | null;
+    originalHeaders: HeaderArray | null;
+    useHeaders: boolean;
+    headerRowProcessed: boolean;
+    renamedHeadersForMeta: Record<string, string> | null;
+    currentRowStartLine: number;
+    currentRowStartOffset: number;
+    /** Quoted status per field. May be a shared readonly array - copy before modifying. */
+    currentRowQuoted: readonly boolean[];
+    currentRawRow: string;
+}
+/**
+ * Create initial parse state with optional header configuration
+ */
+export declare function createParseState(config: Pick<ParseConfig, "headers" | "groupColumnsByName" | "infoOption" | "rawOption">): ParseState;
+/**
+ * Reset info state for next row
+ */
+export declare function resetInfoState(state: ParseState, trackInfo: boolean, trackRaw: boolean, nextLine: number, nextOffset: number): void;
+/**
+ * Get a shared array of false values for unquoted field tracking.
+ * Returns a frozen shared reference for common cases to avoid per-row allocation.
+ *
+ * IMPORTANT: The returned array must NOT be modified. If you need to store
+ * the values, make a copy: `[...getUnquotedArray(n)]` or `.slice(0, n)`.
+ *
+ * @param length - Number of fields in the row
+ * @returns Shared frozen array (for length <= 256) or new array (for larger rows)
+ */
+export declare function getUnquotedArray(length: number): readonly boolean[];

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

@@ -0,0 +1,96 @@
+/**
+ * CSV Parse State
+ *
+ * Defines the ParseState type and factory function for creating
+ * mutable parsing state. Also includes field building operations.
+ */
+import { processHeaders } from "./helpers.js";
+// =============================================================================
+// State Factory
+// =============================================================================
+/**
+ * Create initial parse state with optional header configuration
+ */
+export function createParseState(config) {
+    const state = {
+        lineNumber: 0,
+        dataRowCount: 0,
+        skippedDataRows: 0,
+        truncated: false,
+        headerRow: null,
+        originalHeaders: null,
+        useHeaders: false,
+        headerRowProcessed: false,
+        renamedHeadersForMeta: null,
+        currentRowStartLine: config.infoOption ? 1 : 0,
+        currentRowStartOffset: 0,
+        currentRowQuoted: [],
+        currentRawRow: ""
+    };
+    // Determine header mode
+    const { headers, groupColumnsByName } = config;
+    if (headers === true) {
+        state.useHeaders = true;
+    }
+    else if (Array.isArray(headers)) {
+        const result = processHeaders([], { headers: headers, groupColumnsByName }, null);
+        if (result) {
+            state.headerRow = result.headers;
+            state.originalHeaders = result.originalHeaders;
+            state.renamedHeadersForMeta = result.renamedHeaders;
+        }
+        state.useHeaders = true;
+        state.headerRowProcessed = true;
+    }
+    else if (typeof headers === "function") {
+        state.useHeaders = true;
+    }
+    return state;
+}
+// =============================================================================
+// Info State Management
+// =============================================================================
+/**
+ * Reset info state for next row
+ */
+export function resetInfoState(state, trackInfo, trackRaw, nextLine, nextOffset) {
+    if (trackInfo) {
+        state.currentRowQuoted = [];
+        state.currentRowStartLine = nextLine;
+        state.currentRowStartOffset = nextOffset;
+    }
+    if (trackRaw) {
+        state.currentRawRow = "";
+    }
+}
+// =============================================================================
+// Performance Optimization: Shared False Array for Fast Mode
+// =============================================================================
+/**
+ * Pre-allocated frozen array of false values for fast mode quoted tracking.
+ * In fast mode (no quote detection), all fields are unquoted, so we can
+ * return a shared reference instead of allocating per row.
+ *
+ * IMPORTANT: This array is frozen and must NOT be modified.
+ * Callers should copy if they need to store/modify the values.
+ */
+const SHARED_FALSE_ARRAY_SIZE = 256;
+const SHARED_FALSE_ARRAY = Object.freeze(new Array(SHARED_FALSE_ARRAY_SIZE).fill(false));
+/**
+ * Get a shared array of false values for unquoted field tracking.
+ * Returns a frozen shared reference for common cases to avoid per-row allocation.
+ *
+ * IMPORTANT: The returned array must NOT be modified. If you need to store
+ * the values, make a copy: `[...getUnquotedArray(n)]` or `.slice(0, n)`.
+ *
+ * @param length - Number of fields in the row
+ * @returns Shared frozen array (for length <= 256) or new array (for larger rows)
+ */
+export function getUnquotedArray(length) {
+    if (length <= SHARED_FALSE_ARRAY_SIZE) {
+        // Return shared reference - caller must not modify
+        return SHARED_FALSE_ARRAY;
+    }
+    // Fall back to creating new array for very wide rows
+    return new Array(length).fill(false);
+}

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

@@ -0,0 +1,59 @@
+/**
+ * CSV Parser - Synchronous
+ *
+ * RFC 4180 compliant CSV parser.
+ * Provides parseCsv function and low-level parsing generators.
+ */
+import type { CsvParseOptions, CsvParseArrayOptions, CsvParseObjectOptions, CsvParseResult, CsvRecordError, RecordWithInfo } from "../types.js";
+import type { ParseConfig } from "./config.js";
+import type { ParseState } from "./state.js";
+import type { RowProcessResult } from "./row-processor.js";
+/**
+ * Parse input using fast mode (no quote detection)
+ */
+export declare function parseFastMode(input: string, config: ParseConfig, state: ParseState, errors: CsvRecordError[]): Generator<RowProcessResult, void, undefined>;
+/**
+ * Parse input using Scanner-based batch scanning.
+ * This is a high-performance alternative that uses indexOf-based field scanning
+ * instead of character-by-character parsing.
+ *
+ * Key optimizations:
+ * 1. Uses indexOf to find delimiters/quotes/newlines in bulk
+ * 2. Uses slice for field extraction (avoids string concatenation)
+ * 3. Processes entire rows at once instead of character-by-character
+ */
+export declare function parseWithScanner(input: string, config: ParseConfig, state: ParseState, errors: CsvRecordError[]): Generator<RowProcessResult, void, undefined>;
+/**
+ * Parse CSV string - returns string[][] when no options provided.
+ */
+export declare function parseCsv(input: string): string[][];
+/**
+ * Parse CSV string - returns string[][] when headers is false/undefined and no info option.
+ *
+ * Note: When `info: true` is set, returns CsvParseResult instead.
+ */
+export declare function parseCsv(input: string, options: CsvParseArrayOptions & {
+    info?: false;
+}): string[][];
+/**
+ * Parse CSV string - returns CsvParseResult with RecordWithInfo when info: true (array mode).
+ */
+export declare function parseCsv(input: string, options: CsvParseArrayOptions & {
+    info: true;
+}): CsvParseResult<RecordWithInfo<string[]>>;
+/**
+ * Parse CSV string - returns CsvParseResult when headers are enabled.
+ */
+export declare function parseCsv(input: string, options: CsvParseObjectOptions & {
+    info?: false;
+}): CsvParseResult<Record<string, unknown>>;
+/**
+ * Parse CSV string - returns CsvParseResult with RecordWithInfo when info: true (object mode).
+ */
+export declare function parseCsv(input: string, options: CsvParseObjectOptions & {
+    info: true;
+}): CsvParseResult<RecordWithInfo<Record<string, unknown>>>;
+/**
+ * Parse CSV string - general overload for backward compatibility.
+ */
+export declare function parseCsv(input: string, options: CsvParseOptions): string[][] | CsvParseResult<Record<string, string>> | CsvParseResult<Record<string, unknown>> | CsvParseResult<RecordWithInfo<Record<string, unknown>>> | CsvParseResult<RecordWithInfo<string[]>>;