web-csv-toolbox 0.14.0-next-e45bc4d089f1fb259a7596b9862b3b34e717dab7 → 0.14.0-next-74f4486094d18dbaf4e7492f41a2860ba012985a

package/dist/assertCommonOptions.js.map

@@ -1 +1 @@
-{"version":3,"file":"assertCommonOptions.js","sources":["../src/assertCommonOptions.ts"],"sourcesContent":["import type { CommonOptions } from \"./common/types.ts\";\nimport { CR, LF } from \"./constants.ts\";\n\n/**\n * Asserts that the provided value is a string and satisfies certain conditions.\n * @param value - The value to be checked.\n * @param name - The name of the option.\n * @throws {RangeError} If the value is empty, longer than 1 byte, or includes CR or LF.\n * @throws {TypeError} If the value is not a string.\n */\nfunction assertOptionValue(\n  value: string,\n  name: string,\n): asserts value is string {\n  if (typeof value === \"string\") {\n    switch (true) {\n      case value.length === 0:\n        throw new RangeError(`${name} must not be empty`);\n      case value.length > 1:\n        throw new RangeError(`${name} must be a single character`);\n      case value === LF:\n      case value === CR:\n        throw new RangeError(`${name} must not include CR or LF`);\n      default:\n        break;\n    }\n  } else {\n    throw new TypeError(`${name} must be a string`);\n  }\n}\n\n/**\n * Asserts that the provided options object contains all the required properties.\n * Throws an error if any required property is missing\n * or if the delimiter and quotation length is not 1 byte character,\n * or if the delimiter is the same as the quotation.\n *\n * @example\n *\n * ```ts\n * assertCommonOptions({\n *   quotation: '\"',\n *   delimiter: ',',\n * });\n * ```\n *\n * @param options - The options object to be validated.\n * @throws {RangeError} If any required property is missing or if the delimiter is the same as the quotation.\n * @throws {TypeError} If any required property is not a string.\n */\nexport function assertCommonOptions<\n  Delimiter extends string,\n  Quotation extends string,\n>(\n  options: Required<CommonOptions<Delimiter, Quotation>>,\n): asserts options is Required<CommonOptions<Delimiter, Quotation>> {\n  for (const name of [\"delimiter\", \"quotation\"] as const) {\n    assertOptionValue(options[name], name);\n  }\n  // @ts-ignore: TS doesn't understand that the values are strings\n  if (options.delimiter === options.quotation) {\n    throw new RangeError(\n      \"delimiter must not be the same as quotation, use different characters\",\n    );\n  }\n\n  // Validate maxBufferSize\n  const mbs = options.maxBufferSize;\n  if (\n    !(Number.isFinite(mbs) || mbs === Number.POSITIVE_INFINITY) ||\n    (Number.isFinite(mbs) && (mbs < 1 || !Number.isInteger(mbs)))\n  ) {\n    throw new RangeError(\n      \"maxBufferSize must be a positive integer (in characters) or Number.POSITIVE_INFINITY\",\n    );\n  }\n}\n"],"names":[],"mappings":";;AAUA,SAAS,iBAAA,CACP,OACA,IAAA,EACyB;AACzB,EAAA,IAAI,OAAO,UAAU,QAAA,EAAU;AAC7B,IAAA,QAAQ,IAAA;AAAM,MACZ,KAAK,MAAM,MAAA,KAAW,CAAA;AACpB,QAAA,MAAM,IAAI,UAAA,CAAW,CAAA,EAAG,IAAI,CAAA,kBAAA,CAAoB,CAAA;AAAA,MAClD,KAAK,MAAM,MAAA,GAAS,CAAA;AAClB,QAAA,MAAM,IAAI,UAAA,CAAW,CAAA,EAAG,IAAI,CAAA,2BAAA,CAA6B,CAAA;AAAA,MAC3D,KAAK,KAAA,KAAU,EAAA;AAAA,MACf,KAAK,KAAA,KAAU,EAAA;AACb,QAAA,MAAM,IAAI,UAAA,CAAW,CAAA,EAAG,IAAI,CAAA,0BAAA,CAA4B,CAAA;AAExD;AACJ,EACF,CAAA,MAAO;AACL,IAAA,MAAM,IAAI,SAAA,CAAU,CAAA,EAAG,IAAI,CAAA,iBAAA,CAAmB,CAAA;AAAA,EAChD;AACF;AAqBO,SAAS,oBAId,OAAA,EACkE;AAClE,EAAA,KAAA,MAAW,IAAA,IAAQ,CAAC,WAAA,EAAa,WAAW,CAAA,EAAY;AACtD,IAAA,iBAAA,CAAkB,OAAA,CAAQ,IAAI,CAAA,EAAG,IAAI,CAAA;AAAA,EACvC;AAEA,EAAA,IAAI,OAAA,CAAQ,SAAA,KAAc,OAAA,CAAQ,SAAA,EAAW;AAC3C,IAAA,MAAM,IAAI,UAAA;AAAA,MACR;AAAA,KACF;AAAA,EACF;AAGA,EAAA,MAAM,MAAM,OAAA,CAAQ,aAAA;AACpB,EAAA,IACE,EAAE,MAAA,CAAO,QAAA,CAAS,GAAG,CAAA,IAAK,GAAA,KAAQ,OAAO,iBAAA,CAAA,IACxC,MAAA,CAAO,QAAA,CAAS,GAAG,MAAM,GAAA,GAAM,CAAA,IAAK,CAAC,MAAA,CAAO,SAAA,CAAU,GAAG,CAAA,CAAA,EAC1D;AACA,IAAA,MAAM,IAAI,UAAA;AAAA,MACR;AAAA,KACF;AAAA,EACF;AACF;;;;"}
+{"version":3,"file":"assertCommonOptions.js","sources":["../src/assertCommonOptions.ts"],"sourcesContent":["import type { CommonOptions } from \"./common/types.ts\";\nimport { CR, LF } from \"./constants.ts\";\n\n/**\n * Asserts that the provided value is a string and satisfies certain conditions.\n * @param value - The value to be checked.\n * @param name - The name of the option.\n * @throws {RangeError} If the value is empty, longer than 1 byte, or includes CR or LF.\n * @throws {TypeError} If the value is not a string.\n */\nfunction assertOptionValue(\n  value: string,\n  name: string,\n): asserts value is string {\n  if (typeof value === \"string\") {\n    switch (true) {\n      case value.length === 0:\n        throw new RangeError(`${name} must not be empty`);\n      case value.length > 1:\n        throw new RangeError(`${name} must be a single character`);\n      case value === LF:\n      case value === CR:\n        throw new RangeError(`${name} must not include CR or LF`);\n      default:\n        break;\n    }\n  } else {\n    throw new TypeError(`${name} must be a string`);\n  }\n}\n\n/**\n * Asserts that the provided options object contains all the required properties.\n * Throws an error if any required property is missing\n * or if the delimiter and quotation length is not 1 byte character,\n * or if the delimiter is the same as the quotation.\n *\n * @example\n *\n * ```ts\n * assertCommonOptions({\n *   quotation: '\"',\n *   delimiter: ',',\n * });\n * ```\n *\n * @param options - The options object to be validated.\n * @throws {RangeError} If any required property is missing or if the delimiter is the same as the quotation.\n * @throws {TypeError} If any required property is not a string.\n */\nexport function assertCommonOptions<\n  Delimiter extends string,\n  Quotation extends string,\n>(\n  options: Required<Omit<CommonOptions<Delimiter, Quotation>, \"source\">>,\n): asserts options is Required<\n  Omit<CommonOptions<Delimiter, Quotation>, \"source\">\n> {\n  for (const name of [\"delimiter\", \"quotation\"] as const) {\n    assertOptionValue(options[name], name);\n  }\n  // @ts-ignore: TS doesn't understand that the values are strings\n  if (options.delimiter === options.quotation) {\n    throw new RangeError(\n      \"delimiter must not be the same as quotation, use different characters\",\n    );\n  }\n\n  // Validate maxBufferSize\n  const mbs = options.maxBufferSize;\n  if (\n    !(Number.isFinite(mbs) || mbs === Number.POSITIVE_INFINITY) ||\n    (Number.isFinite(mbs) && (mbs < 1 || !Number.isInteger(mbs)))\n  ) {\n    throw new RangeError(\n      \"maxBufferSize must be a positive integer (in characters) or Number.POSITIVE_INFINITY\",\n    );\n  }\n}\n"],"names":[],"mappings":";;AAUA,SAAS,iBAAA,CACP,OACA,IAAA,EACyB;AACzB,EAAA,IAAI,OAAO,UAAU,QAAA,EAAU;AAC7B,IAAA,QAAQ,IAAA;AAAM,MACZ,KAAK,MAAM,MAAA,KAAW,CAAA;AACpB,QAAA,MAAM,IAAI,UAAA,CAAW,CAAA,EAAG,IAAI,CAAA,kBAAA,CAAoB,CAAA;AAAA,MAClD,KAAK,MAAM,MAAA,GAAS,CAAA;AAClB,QAAA,MAAM,IAAI,UAAA,CAAW,CAAA,EAAG,IAAI,CAAA,2BAAA,CAA6B,CAAA;AAAA,MAC3D,KAAK,KAAA,KAAU,EAAA;AAAA,MACf,KAAK,KAAA,KAAU,EAAA;AACb,QAAA,MAAM,IAAI,UAAA,CAAW,CAAA,EAAG,IAAI,CAAA,0BAAA,CAA4B,CAAA;AAExD;AACJ,EACF,CAAA,MAAO;AACL,IAAA,MAAM,IAAI,SAAA,CAAU,CAAA,EAAG,IAAI,CAAA,iBAAA,CAAmB,CAAA;AAAA,EAChD;AACF;AAqBO,SAAS,oBAId,OAAA,EAGA;AACA,EAAA,KAAA,MAAW,IAAA,IAAQ,CAAC,WAAA,EAAa,WAAW,CAAA,EAAY;AACtD,IAAA,iBAAA,CAAkB,OAAA,CAAQ,IAAI,CAAA,EAAG,IAAI,CAAA;AAAA,EACvC;AAEA,EAAA,IAAI,OAAA,CAAQ,SAAA,KAAc,OAAA,CAAQ,SAAA,EAAW;AAC3C,IAAA,MAAM,IAAI,UAAA;AAAA,MACR;AAAA,KACF;AAAA,EACF;AAGA,EAAA,MAAM,MAAM,OAAA,CAAQ,aAAA;AACpB,EAAA,IACE,EAAE,MAAA,CAAO,QAAA,CAAS,GAAG,CAAA,IAAK,GAAA,KAAQ,OAAO,iBAAA,CAAA,IACxC,MAAA,CAAO,QAAA,CAAS,GAAG,MAAM,GAAA,GAAM,CAAA,IAAK,CAAC,MAAA,CAAO,SAAA,CAAU,GAAG,CAAA,CAAA,EAC1D;AACA,IAAA,MAAM,IAAI,UAAA;AAAA,MACR;AAAA,KACF;AAAA,EACF;AACF;;;;"}

package/dist/common/errors.d.ts

@@ -7,6 +7,22 @@ export interface ParseErrorOptions extends ErrorOptions {
      * The position where the error occurred.
      */
     position?: Position;
+    /**
+     * The row number where the error occurred.
+     *
+     * @remarks
+     * This represents the logical CSV row number (includes header if present),
+     * useful for error reporting to users.
+     */
+    rowNumber?: number;
+    /**
+     * Source identifier (e.g., filename) for error reporting.
+     *
+     * @remarks
+     * A human-readable identifier for the CSV source to help locate
+     * which file or stream caused the error.
+     */
+    source?: string;
 }
 /**
  * Error class for parse errors.
@@ -23,5 +39,21 @@ export declare class ParseError extends SyntaxError {
      * The position where the error occurred.
      */
     position?: Position;
+    /**
+     * The row number where the error occurred.
+     *
+     * @remarks
+     * This represents the logical CSV row number (includes header if present),
+     * useful for error reporting to users.
+     */
+    rowNumber?: number;
+    /**
+     * Source identifier (e.g., filename) for error reporting.
+     *
+     * @remarks
+     * A human-readable identifier for the CSV source to help locate
+     * which file or stream caused the error.
+     */
+    source?: string;
     constructor(message?: string, options?: ParseErrorOptions);
 }

package/dist/common/errors.js

@@ -3,10 +3,28 @@ class ParseError extends SyntaxError {
    * The position where the error occurred.
    */
   position;
+  /**
+   * The row number where the error occurred.
+   *
+   * @remarks
+   * This represents the logical CSV row number (includes header if present),
+   * useful for error reporting to users.
+   */
+  rowNumber;
+  /**
+   * Source identifier (e.g., filename) for error reporting.
+   *
+   * @remarks
+   * A human-readable identifier for the CSV source to help locate
+   * which file or stream caused the error.
+   */
+  source;
   constructor(message, options) {
     super(message, { cause: options?.cause });
     this.name = "ParseError";
     this.position = options?.position;
+    this.rowNumber = options?.rowNumber;
+    this.source = options?.source;
   }
 }
 

package/dist/common/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sources":["../../src/common/errors.ts"],"sourcesContent":["import type { Position } from \"./types.js\";\n\n/**\n * Options for creating a parse error.\n */\nexport interface ParseErrorOptions extends ErrorOptions {\n  /**\n   * The position where the error occurred.\n   */\n  position?: Position;\n}\n\n/**\n * Error class for parse errors.\n *\n * @remarks\n * This error is thrown when a parsing error occurs.\n * {@link ParseError} is a subclass of {@link !SyntaxError}.\n *\n * This is in reference to the specification\n * that the error thrown when a parse error occurs in the {@link !JSON.parse} function is {@link !SyntaxError}.\n */\nexport class ParseError extends SyntaxError {\n  /**\n   * The position where the error occurred.\n   */\n  public position?: Position;\n\n  constructor(message?: string, options?: ParseErrorOptions) {\n    super(message, { cause: options?.cause });\n    this.name = \"ParseError\";\n    this.position = options?.position;\n  }\n}\n"],"names":[],"mappings":"AAsBO,MAAM,mBAAmB,WAAA,CAAY;AAAA;AAAA;AAAA;AAAA,EAInC,QAAA;AAAA,EAEP,WAAA,CAAY,SAAkB,OAAA,EAA6B;AACzD,IAAA,KAAA,CAAM,OAAA,EAAS,EAAE,KAAA,EAAO,OAAA,EAAS,OAAO,CAAA;AACxC,IAAA,IAAA,CAAK,IAAA,GAAO,YAAA;AACZ,IAAA,IAAA,CAAK,WAAW,OAAA,EAAS,QAAA;AAAA,EAC3B;AACF;;;;"}
+{"version":3,"file":"errors.js","sources":["../../src/common/errors.ts"],"sourcesContent":["import type { Position } from \"./types.js\";\n\n/**\n * Options for creating a parse error.\n */\nexport interface ParseErrorOptions extends ErrorOptions {\n  /**\n   * The position where the error occurred.\n   */\n  position?: Position;\n  /**\n   * The row number where the error occurred.\n   *\n   * @remarks\n   * This represents the logical CSV row number (includes header if present),\n   * useful for error reporting to users.\n   */\n  rowNumber?: number;\n  /**\n   * Source identifier (e.g., filename) for error reporting.\n   *\n   * @remarks\n   * A human-readable identifier for the CSV source to help locate\n   * which file or stream caused the error.\n   */\n  source?: string;\n}\n\n/**\n * Error class for parse errors.\n *\n * @remarks\n * This error is thrown when a parsing error occurs.\n * {@link ParseError} is a subclass of {@link !SyntaxError}.\n *\n * This is in reference to the specification\n * that the error thrown when a parse error occurs in the {@link !JSON.parse} function is {@link !SyntaxError}.\n */\nexport class ParseError extends SyntaxError {\n  /**\n   * The position where the error occurred.\n   */\n  public position?: Position;\n  /**\n   * The row number where the error occurred.\n   *\n   * @remarks\n   * This represents the logical CSV row number (includes header if present),\n   * useful for error reporting to users.\n   */\n  public rowNumber?: number;\n  /**\n   * Source identifier (e.g., filename) for error reporting.\n   *\n   * @remarks\n   * A human-readable identifier for the CSV source to help locate\n   * which file or stream caused the error.\n   */\n  public source?: string;\n\n  constructor(message?: string, options?: ParseErrorOptions) {\n    super(message, { cause: options?.cause });\n    this.name = \"ParseError\";\n    this.position = options?.position;\n    this.rowNumber = options?.rowNumber;\n    this.source = options?.source;\n  }\n}\n"],"names":[],"mappings":"AAsCO,MAAM,mBAAmB,WAAA,CAAY;AAAA;AAAA;AAAA;AAAA,EAInC,QAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,SAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAA;AAAA,EAEP,WAAA,CAAY,SAAkB,OAAA,EAA6B;AACzD,IAAA,KAAA,CAAM,OAAA,EAAS,EAAE,KAAA,EAAO,OAAA,EAAS,OAAO,CAAA;AACxC,IAAA,IAAA,CAAK,IAAA,GAAO,YAAA;AACZ,IAAA,IAAA,CAAK,WAAW,OAAA,EAAS,QAAA;AACzB,IAAA,IAAA,CAAK,YAAY,OAAA,EAAS,SAAA;AAC1B,IAAA,IAAA,CAAK,SAAS,OAAA,EAAS,MAAA;AAAA,EACzB;AACF;;;;"}

package/dist/common/types.d.ts

@@ -1,5 +1,6 @@
 import { DEFAULT_DELIMITER, DEFAULT_QUOTATION } from '../constants.ts';
-import { Join } from '../utils/types.ts';
+import { WorkerPool } from '../execution/worker/helpers/WorkerPool.ts';
+import { JoinCSVFields } from '../utils/types.ts';
 import { Field, FieldDelimiter, RecordDelimiter } from './constants.ts';
 /**
  * Position object.
@@ -34,12 +35,49 @@ export interface TokenLocation {
      */
     end: Position;
     /**
-     * Row number.
+     * Row number in the CSV (includes header if present).
      * Starts from 1.
      *
      * @remarks
-     * This represents the logical row number in the CSV,
-     * counting from 1 for the first row, whether it is a header or not.
+     * This represents the logical CSV row number, not the physical line number.
+     * A single CSV row may span multiple lines if fields contain newline
+     * characters within quotes.
+     *
+     * **Important distinction**:
+     * - `line`: Physical line number (incremented by `\n` characters)
+     * - `rowNumber`: Logical CSV row (incremented by record delimiters)
+     *
+     * The header row (if present) is counted as row 1. This corresponds to
+     * the physical row position in the file, making it easy to locate in editors.
+     *
+     * For physical line numbers, use `start.line` or `end.line`.
+     *
+     * **Primary use case**: Error reporting. This field allows errors to be
+     * reported with both physical position (`line`, `column`) and logical
+     * row context (`rowNumber`), making it easier for users to locate
+     * issues in their CSV data.
+     *
+     * @example
+     * ```csv
+     * name,description       <- rowNumber: 1 (header)
+     * Alice,"Lives in
+     * New York"              <- rowNumber: 2 (spans line 2-3)
+     * Bob,"Works"            <- rowNumber: 3 (line 4)
+     * ```
+     * - Header: `rowNumber: 1`
+     * - Alice's row: `start.line: 2, end.line: 3, rowNumber: 2`
+     * - Bob's row: `start.line: 4, end.line: 4, rowNumber: 3`
+     *
+     * @example Error reporting
+     * ```ts
+     * try {
+     *   await parseString(csv);
+     * } catch (error) {
+     *   if (error instanceof ParseError) {
+     *     console.error(`Error at row ${error.rowNumber}, line ${error.position?.line}`);
+     *   }
+     * }
+     * ```
      */
     rowNumber: number;
 }
@@ -128,11 +166,37 @@ export interface AbortSignalOptions {
      */
     signal?: AbortSignal;
 }
+/**
+ * Source identifier option for error reporting.
+ * @category Types
+ */
+export interface SourceOption {
+    /**
+     * Source identifier for error reporting (e.g., filename, description).
+     *
+     * @remarks
+     * This option allows you to specify a human-readable identifier for the CSV source
+     * that will be included in error messages. This is particularly useful when parsing
+     * multiple files or streams to help identify which source caused an error.
+     *
+     * **Security Note**: Do not include sensitive information (API keys, tokens, full URLs)
+     * in this field as it may be exposed in error messages and logs.
+     *
+     * @example
+     * ```ts
+     * parseString(csv, { source: "users.csv" });
+     * // Error: Field count exceeded at row 5 in "users.csv"
+     * ```
+     *
+     * @default undefined
+     */
+    source?: string;
+}
 /**
  * CSV Common Options.
  * @category Types
  */
-export interface CommonOptions<Delimiter extends string, Quotation extends string> {
+export interface CommonOptions<Delimiter extends string, Quotation extends string> extends SourceOption {
     /**
      * CSV field delimiter.
      * If you want to parse TSV, specify `'\t'`.
@@ -340,6 +404,15 @@ export interface BinaryOptions {
  * @category Types
  */
 export interface CSVLexerTransformerOptions<Delimiter extends string = DEFAULT_DELIMITER, Quotation extends string = DEFAULT_QUOTATION> extends CommonOptions<Delimiter, Quotation>, AbortSignalOptions {
+    /**
+     * How often to check for backpressure (in number of tokens processed).
+     *
+     * Lower values = more responsive to backpressure but slight performance overhead.
+     * Higher values = less overhead but slower backpressure response.
+     *
+     * @default 100
+     */
+    backpressureCheckInterval?: number;
 }
 /**
  * CSV Record Assembler Options.
@@ -352,7 +425,7 @@ export interface CSVLexerTransformerOptions<Delimiter extends string = DEFAULT_D
  * If you don't specify `header`,
  * the first record will be treated as a header.
  */
-export interface CSVRecordAssemblerOptions<Header extends ReadonlyArray<string>> extends AbortSignalOptions {
+export interface CSVRecordAssemblerOptions<Header extends ReadonlyArray<string>> extends SourceOption, AbortSignalOptions {
     /**
      * CSV header.
      *
@@ -386,6 +459,15 @@ export interface CSVRecordAssemblerOptions<Header extends ReadonlyArray<string>>
      * @default false
      */
     skipEmptyLines?: boolean;
+    /**
+     * How often to check for backpressure (in number of records processed).
+     *
+     * Lower values = more responsive to backpressure but slight performance overhead.
+     * Higher values = less overhead but slower backpressure response.
+     *
+     * @default 10
+     */
+    backpressureCheckInterval?: number;
 }
 /**
  * Worker communication strategy.
@@ -421,27 +503,168 @@ export interface EngineFallbackInfo {
     error?: Error;
 }
 /**
- * Engine configuration for CSV parsing.
+ * Backpressure monitoring intervals (count-based).
  *
- * All parsing engine settings are unified in this interface.
+ * Controls how frequently the internal parsers check for backpressure
+ * during streaming operations, based on the number of tokens/records processed.
  *
+ * @experimental This API may change in future versions based on performance research.
  * @category Types
  */
-export interface EngineConfig {
+export interface BackpressureCheckInterval {
     /**
-     * Execute in Worker thread.
+     * Check interval for the lexer stage (number of tokens processed).
+     *
+     * Lower values provide better responsiveness to backpressure but may have
+     * slight performance overhead.
+     *
+     * @default 100
+     */
+    lexer?: number;
+    /**
+     * Check interval for the assembler stage (number of records processed).
+     *
+     * Lower values provide better responsiveness to backpressure but may have
+     * slight performance overhead.
+     *
+     * @default 10
+     */
+    assembler?: number;
+}
+/**
+ * Internal streaming queuing strategies configuration.
+ *
+ * Controls the internal queuing behavior of the CSV parser's streaming pipeline.
+ * This affects memory usage and backpressure handling for large streaming operations.
+ *
+ * @remarks
+ * The CSV parser uses a two-stage pipeline:
+ * 1. **Lexer**: String → Token
+ * 2. **Assembler**: Token → CSVRecord
+ *
+ * Each stage has both writable (input) and readable (output) sides.
+ *
+ * @experimental This API may change in future versions based on performance research.
+ * @category Types
+ */
+export interface QueuingStrategyConfig {
+    /**
+     * Queuing strategy for the lexer's writable side (string input).
+     *
+     * Controls how string chunks are buffered before being processed by the lexer.
+     *
+     * @default `{ highWaterMark: 65536 }` (≈64KB of characters)
+     */
+    lexerWritable?: QueuingStrategy<string>;
+    /**
+     * Queuing strategy for the lexer's readable side (token output).
+     *
+     * Controls how tokens are buffered after being produced by the lexer
+     * before being consumed by the assembler.
+     *
+     * @default `{ highWaterMark: 1024 }` (1024 tokens)
+     */
+    lexerReadable?: QueuingStrategy<Token>;
+    /**
+     * Queuing strategy for the assembler's writable side (token input).
+     *
+     * Controls how tokens are buffered before being processed by the assembler.
+     * This is the input side of the assembler, receiving tokens from the lexer.
+     *
+     * @default `{ highWaterMark: 1024 }` (1024 tokens)
+     */
+    assemblerWritable?: QueuingStrategy<Token>;
+    /**
+     * Queuing strategy for the assembler's readable side (record output).
+     *
+     * Controls how CSV records are buffered after being assembled.
+     *
+     * @default `{ highWaterMark: 256 }` (256 records)
+     */
+    assemblerReadable?: QueuingStrategy<CSVRecord<any>>;
+}
+/**
+ * Base engine configuration shared by all execution modes.
+ *
+ * @category Types
+ */
+interface BaseEngineConfig {
+    /**
+     * Use WASM implementation.
+     *
+     * Requires prior initialization with {@link loadWASM}.
      *
      * @default false
      *
-     * @example Worker execution
+     * @example Main thread + WASM
      * ```ts
-     * parse(csv, { engine: { worker: true } })
+     * import { loadWASM, parse } from 'web-csv-toolbox';
+     *
+     * await loadWASM();
+     * parse(csv, { engine: { wasm: true } })
+     * ```
+     *
+     * @example Worker + WASM
+     * ```ts
+     * await loadWASM();
+     * parse(csv, { engine: { worker: true, wasm: true } })
      * ```
      */
-    worker?: boolean;
+    wasm?: boolean;
+    /**
+     * Blob reading strategy threshold (in bytes).
+     * Only applicable for `parseBlob()` and `parseFile()`.
+     *
+     * Determines when to use `blob.arrayBuffer()` vs `blob.stream()`:
+     * - Files smaller than threshold: Use `blob.arrayBuffer()` + `parseBinary()`
+     *   - ✅ Faster for small files
+     *   - ❌ Loads entire file into memory
+     * - Files equal to or larger than threshold: Use `blob.stream()` + `parseUint8ArrayStream()`
+     *   - ✅ Memory-efficient for large files
+     *   - ❌ Slight streaming overhead
+     *
+     * @default 1_048_576 (1MB)
+     */
+    arrayBufferThreshold?: number;
+    /**
+     * Backpressure monitoring intervals (count-based: number of tokens/records processed).
+     *
+     * @default { lexer: 100, assembler: 10 }
+     * @experimental
+     */
+    backpressureCheckInterval?: BackpressureCheckInterval;
+    /**
+     * Internal streaming queuing strategies.
+     *
+     * @experimental
+     */
+    queuingStrategy?: QueuingStrategyConfig;
+}
+/**
+ * Engine configuration for main thread execution.
+ *
+ * @category Types
+ */
+export interface MainThreadEngineConfig extends BaseEngineConfig {
+    /**
+     * Execute in Worker thread.
+     *
+     * @default false
+     */
+    worker?: false;
+}
+/**
+ * Engine configuration for worker thread execution.
+ *
+ * @category Types
+ */
+export interface WorkerEngineConfig extends BaseEngineConfig {
+    /**
+     * Execute in Worker thread.
+     */
+    worker: true;
     /**
      * Custom Worker URL.
-     * Only applicable when `worker: true`.
      *
      * If not provided, uses the bundled worker.
      *
@@ -461,7 +684,6 @@ export interface EngineConfig {
     workerURL?: string | URL;
     /**
      * Worker pool for managing worker lifecycle.
-     * Only applicable when `worker: true`.
      *
      * When provided, the parsing function will use this pool's worker instance
      * instead of creating/reusing a module-level singleton worker.
@@ -498,32 +720,9 @@ export interface EngineConfig {
      * // Worker is reused for both operations
      * ```
      */
-    workerPool?: import('../execution/worker/helpers/WorkerPool.ts').WorkerPool;
-    /**
-     * Use WASM implementation.
-     *
-     * Requires prior initialization with {@link loadWASM}.
-     *
-     * @default false
-     *
-     * @example Main thread + WASM
-     * ```ts
-     * import { loadWASM, parse } from 'web-csv-toolbox';
-     *
-     * await loadWASM();
-     * parse(csv, { engine: { wasm: true } })
-     * ```
-     *
-     * @example Worker + WASM
-     * ```ts
-     * await loadWASM();
-     * parse(csv, { engine: { worker: true, wasm: true } })
-     * ```
-     */
-    wasm?: boolean;
+    workerPool?: WorkerPool;
     /**
      * Worker communication strategy.
-     * Only applicable when `worker: true`.
      *
      * - `"message-streaming"` (default): Message-based streaming
      *   - ✅ All browsers including Safari
@@ -563,7 +762,6 @@ export interface EngineConfig {
     workerStrategy?: WorkerCommunicationStrategy;
     /**
      * Strict mode: disable automatic fallback.
-     * Only applicable when `workerStrategy: "stream-transfer"`.
      *
      * When enabled:
      * - Throws error immediately if stream transfer fails
@@ -621,6 +819,15 @@ export interface EngineConfig {
      */
     onFallback?: (info: EngineFallbackInfo) => void;
 }
+/**
+ * Engine configuration for CSV parsing.
+ *
+ * All parsing engine settings are unified in this type.
+ * Use discriminated union to ensure type-safe configuration based on worker mode.
+ *
+ * @category Types
+ */
+export type EngineConfig = MainThreadEngineConfig | WorkerEngineConfig;
 /**
  * Engine configuration options.
  *
@@ -689,41 +896,17 @@ export type CSVRecord<Header extends ReadonlyArray<string>> = Record<Header[numb
  *
  * @category Types
  */
-export type CSVString<Header extends ReadonlyArray<string> = [], Delimiter extends string = DEFAULT_DELIMITER, Quotation extends string = DEFAULT_QUOTATION> = Header extends readonly [string, ...string[]] ? Join<Header, Delimiter, Quotation> | ReadableStream<Join<Header, Delimiter, Quotation>> : string | ReadableStream<string>;
+export type CSVString<Header extends ReadonlyArray<string> = [], Delimiter extends string = DEFAULT_DELIMITER, Quotation extends string = DEFAULT_QUOTATION> = Header extends readonly [string, ...string[]] ? JoinCSVFields<Header, Delimiter, Quotation> | ReadableStream<JoinCSVFields<Header, Delimiter, Quotation>> : string | ReadableStream<string>;
 /**
  * CSV Binary.
  *
  * @category Types
  */
 export type CSVBinary = ReadableStream<Uint8Array> | Response | Request | Blob | ArrayBuffer | Uint8Array;
-/**
- * Backpressure monitoring options.
- *
- * @category Types
- */
-export interface BackpressureOptions {
-    /**
-     * How often to check for backpressure (in number of items processed).
-     *
-     * Lower values = more responsive to backpressure but slight performance overhead.
-     * Higher values = less overhead but slower backpressure response.
-     *
-     * Default:
-     * - CSVLexerTransformer: 100 tokens
-     * - CSVRecordAssemblerTransformer: 10 records
-     */
-    checkInterval?: number;
-}
-/**
- * Extended queuing strategy with backpressure monitoring options.
- *
- * @category Types
- */
-export interface ExtendedQueuingStrategy<T> extends QueuingStrategy<T>, BackpressureOptions {
-}
 /**
  * CSV.
  *
  * @category Types
  */
 export type CSV<Header extends ReadonlyArray<string> = [], Delimiter extends string = DEFAULT_DELIMITER, Quotation extends string = DEFAULT_QUOTATION> = Header extends [] ? CSVString | CSVBinary : CSVString<Header, Delimiter, Quotation>;
+export {};

package/dist/constants.d.ts

@@ -17,3 +17,15 @@ export declare const DEFAULT_DELIMITER = ",";
 export type DEFAULT_DELIMITER = typeof DEFAULT_DELIMITER;
 export declare const DEFAULT_QUOTATION = "\"";
 export type DEFAULT_QUOTATION = typeof DEFAULT_QUOTATION;
+/**
+ * Default threshold (in bytes) for Blob reading strategy.
+ *
+ * Files smaller than this use `blob.arrayBuffer()` (faster),
+ * files equal or larger use `blob.stream()` (memory-efficient).
+ *
+ * This value is determined by benchmarks.
+ *
+ * @category Constants
+ */
+export declare const DEFAULT_ARRAY_BUFFER_THRESHOLD = 1048576;
+export type DEFAULT_ARRAY_BUFFER_THRESHOLD = typeof DEFAULT_ARRAY_BUFFER_THRESHOLD;

package/dist/constants.js

@@ -5,6 +5,7 @@ const COMMA = ",";
 const DOUBLE_QUOTE = '"';
 const DEFAULT_DELIMITER = COMMA;
 const DEFAULT_QUOTATION = DOUBLE_QUOTE;
+const DEFAULT_ARRAY_BUFFER_THRESHOLD = 1048576;
 
-export { COMMA, CR, CRLF, DEFAULT_DELIMITER, DEFAULT_QUOTATION, DOUBLE_QUOTE, LF };
+export { COMMA, CR, CRLF, DEFAULT_ARRAY_BUFFER_THRESHOLD, DEFAULT_DELIMITER, DEFAULT_QUOTATION, DOUBLE_QUOTE, LF };
 //# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sources":["../src/constants.ts"],"sourcesContent":["export const CR = \"\\r\";\nexport type CR = typeof CR;\n\nexport const CRLF = \"\\r\\n\";\nexport type CRLF = typeof CRLF;\n\nexport const LF = \"\\n\";\nexport type LF = typeof LF;\n\nexport type Newline = CRLF | CR | LF;\n\n/**\n * COMMA is a symbol for comma(,).\n */\nexport const COMMA = \",\";\n\n/**\n * DOUBLE_QUOTE is a symbol for double quote(\").\n */\nexport const DOUBLE_QUOTE = '\"';\n\nexport const DEFAULT_DELIMITER = COMMA;\nexport type DEFAULT_DELIMITER = typeof DEFAULT_DELIMITER;\n\nexport const DEFAULT_QUOTATION = DOUBLE_QUOTE;\nexport type DEFAULT_QUOTATION = typeof DEFAULT_QUOTATION;\n"],"names":[],"mappings":"AAAO,MAAM,EAAA,GAAK;AAGX,MAAM,IAAA,GAAO;AAGb,MAAM,EAAA,GAAK;AAQX,MAAM,KAAA,GAAQ;AAKd,MAAM,YAAA,GAAe;AAErB,MAAM,iBAAA,GAAoB;AAG1B,MAAM,iBAAA,GAAoB;;;;"}
+{"version":3,"file":"constants.js","sources":["../src/constants.ts"],"sourcesContent":["export const CR = \"\\r\";\nexport type CR = typeof CR;\n\nexport const CRLF = \"\\r\\n\";\nexport type CRLF = typeof CRLF;\n\nexport const LF = \"\\n\";\nexport type LF = typeof LF;\n\nexport type Newline = CRLF | CR | LF;\n\n/**\n * COMMA is a symbol for comma(,).\n */\nexport const COMMA = \",\";\n\n/**\n * DOUBLE_QUOTE is a symbol for double quote(\").\n */\nexport const DOUBLE_QUOTE = '\"';\n\nexport const DEFAULT_DELIMITER = COMMA;\nexport type DEFAULT_DELIMITER = typeof DEFAULT_DELIMITER;\n\nexport const DEFAULT_QUOTATION = DOUBLE_QUOTE;\nexport type DEFAULT_QUOTATION = typeof DEFAULT_QUOTATION;\n\n/**\n * Default threshold (in bytes) for Blob reading strategy.\n *\n * Files smaller than this use `blob.arrayBuffer()` (faster),\n * files equal or larger use `blob.stream()` (memory-efficient).\n *\n * This value is determined by benchmarks.\n *\n * @category Constants\n */\nexport const DEFAULT_ARRAY_BUFFER_THRESHOLD = 1048576; // 1MB\nexport type DEFAULT_ARRAY_BUFFER_THRESHOLD =\n  typeof DEFAULT_ARRAY_BUFFER_THRESHOLD;\n"],"names":[],"mappings":"AAAO,MAAM,EAAA,GAAK;AAGX,MAAM,IAAA,GAAO;AAGb,MAAM,EAAA,GAAK;AAQX,MAAM,KAAA,GAAQ;AAKd,MAAM,YAAA,GAAe;AAErB,MAAM,iBAAA,GAAoB;AAG1B,MAAM,iBAAA,GAAoB;AAa1B,MAAM,8BAAA,GAAiC;;;;"}