web-csv-toolbox 0.14.0-next-386eebeaafe5857e28c876345c14c9fe5f1a3774 → 0.14.0-next-978b88933762ecc27270ce746b80a3fa7ed8c4f7

package/dist/CSVRecordAssemblerTransformer.js.map

@@ -1 +1 @@
-{"version":3,"file":"CSVRecordAssemblerTransformer.js","sources":["../src/CSVRecordAssemblerTransformer.ts"],"sourcesContent":["import { CSVRecordAssembler } from \"./CSVRecordAssembler.ts\";\nimport type {\n  CSVRecord,\n  CSVRecordAssemblerOptions,\n  ExtendedQueuingStrategy,\n  Token,\n} from \"./common/types.ts\";\n\n/**\n * A transform stream that converts a stream of tokens into a stream of CSV records.\n *\n * @template Header The type of the header row.\n * @param options - CSV-specific options (header, maxFieldCount, etc.)\n * @param writableStrategy - Strategy for the writable side (default: `{ highWaterMark: 1024, size: () => 1, checkInterval: 10 }`)\n * @param readableStrategy - Strategy for the readable side (default: `{ highWaterMark: 256, size: () => 1, checkInterval: 10 }`)\n *\n * @category Low-level API\n *\n * @remarks\n * Follows the Web Streams API pattern where queuing strategies are passed as\n * constructor arguments, similar to the standard `TransformStream`.\n *\n * **Default Queuing Strategy:**\n * - Writable side: Counts each token as 1. Default highWaterMark is 1024 tokens.\n * - Readable side: Counts each record as 1. Default highWaterMark is 256 records.\n *\n * **Backpressure Handling:**\n * The transformer monitors `controller.desiredSize` and yields to the event loop when backpressure\n * is detected (desiredSize ≤ 0). This prevents blocking the main thread during heavy processing\n * and allows the downstream consumer to catch up.\n *\n * These defaults are starting points based on data flow characteristics, not empirical benchmarks.\n * Optimal values depend on your runtime environment, data size, and performance requirements.\n *\n * @example Parse a CSV with headers by data\n *  ```ts\n * new ReadableStream({\n *   start(controller) {\n *     controller.enqueue(\"name,age\\r\\n\");\n *     controller.enqueue(\"Alice,20\\r\\n\");\n *     controller.enqueue(\"Bob,25\\r\\n\");\n *     controller.enqueue(\"Charlie,30\\r\\n\");\n *     controller.close();\n *   })\n *   .pipeThrough(new CSVLexerTransformer())\n *   .pipeThrough(new CSVRecordAssemblerTransformer())\n *   .pipeTo(new WritableStream({ write(row) { console.log(row); }}));\n * // { name: \"Alice\", age: \"20\" }\n * // { name: \"Bob\", age: \"25\" }\n * // { name: \"Charlie\", age: \"30\" }\n * ```\n *\n * @example Parse a CSV with headers by options\n * ```ts\n * new ReadableStream({\n *   start(controller) {\n *     controller.enqueue(\"Alice,20\\r\\n\");\n *     controller.enqueue(\"Bob,25\\r\\n\");\n *     controller.enqueue(\"Charlie,30\\r\\n\");\n *     controller.close();\n *   }\n * })\n * .pipeThrough(new CSVLexerTransformer())\n * .pipeThrough(new CSVRecordAssemblerTransformer({ header: [\"name\", \"age\"] }))\n * .pipeTo(new WritableStream({ write(row) { console.log(row); }}));\n * // { name: \"Alice\", age: \"20\" }\n * // { name: \"Bob\", age: \"25\" }\n * // { name: \"Charlie\", age: \"30\" }\n * ```\n *\n * @example Custom queuing strategies with backpressure tuning\n * ```ts\n * const transformer = new CSVRecordAssemblerTransformer(\n *   {},\n *   {\n *     highWaterMark: 2048,  // 2048 tokens\n *     size: () => 1,        // Each token counts as 1\n *     checkInterval: 20     // Check backpressure every 20 records\n *   },\n *   {\n *     highWaterMark: 512,   // 512 records\n *     size: () => 1,        // Each record counts as 1\n *     checkInterval: 5      // Check backpressure every 5 records\n *   }\n * );\n *\n * await tokenStream\n *   .pipeThrough(transformer)\n *   .pipeTo(yourRecordProcessor);\n * ```\n */\nexport class CSVRecordAssemblerTransformer<\n  Header extends ReadonlyArray<string>,\n> extends TransformStream<Token, CSVRecord<Header>> {\n  public readonly assembler: CSVRecordAssembler<Header>;\n\n  /**\n   * Yields to the event loop to allow backpressure handling.\n   * Can be overridden for testing purposes.\n   * @internal\n   */\n  protected async yieldToEventLoop(): Promise<void> {\n    await new Promise((resolve) => setTimeout(resolve, 0));\n  }\n\n  constructor(\n    options: CSVRecordAssemblerOptions<Header> = {},\n    writableStrategy: ExtendedQueuingStrategy<Token> = {\n      highWaterMark: 1024, // 1024 tokens\n      size: () => 1, // Each token counts as 1\n      checkInterval: 10, // Check backpressure every 10 records\n    },\n    readableStrategy: ExtendedQueuingStrategy<CSVRecord<Header>> = {\n      highWaterMark: 256, // 256 records\n      size: () => 1, // Each record counts as 1\n      checkInterval: 10, // Check backpressure every 10 records\n    },\n  ) {\n    const assembler = new CSVRecordAssembler(options);\n    const checkInterval =\n      writableStrategy.checkInterval ?? readableStrategy.checkInterval ?? 10;\n\n    super(\n      {\n        transform: async (token, controller) => {\n          try {\n            let recordCount = 0;\n            // Pass single token directly to assemble (no array creation)\n            for (const record of assembler.assemble(token, { stream: true })) {\n              controller.enqueue(record);\n              recordCount++;\n\n              // Check backpressure periodically based on checkInterval\n              if (\n                recordCount % checkInterval === 0 &&\n                controller.desiredSize !== null &&\n                controller.desiredSize <= 0\n              ) {\n                // Yield to event loop when backpressure is detected\n                await this.yieldToEventLoop();\n              }\n            }\n          } catch (error) {\n            controller.error(error);\n          }\n        },\n        flush: async (controller) => {\n          try {\n            let recordCount = 0;\n            // Call assemble without arguments to flush\n            for (const record of assembler.assemble()) {\n              controller.enqueue(record);\n              recordCount++;\n\n              // Check backpressure periodically based on checkInterval\n              if (\n                recordCount % checkInterval === 0 &&\n                controller.desiredSize !== null &&\n                controller.desiredSize <= 0\n              ) {\n                await this.yieldToEventLoop();\n              }\n            }\n          } catch (error) {\n            controller.error(error);\n          }\n        },\n      },\n      writableStrategy,\n      readableStrategy,\n    );\n    this.assembler = assembler;\n  }\n}\n"],"names":[],"mappings":";;AA2FO,MAAM,sCAEH,eAAA,CAA0C;AAAA,EAClC,SAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOhB,MAAgB,gBAAA,GAAkC;AAChD,IAAA,MAAM,IAAI,OAAA,CAAQ,CAAC,YAAY,UAAA,CAAW,OAAA,EAAS,CAAC,CAAC,CAAA;AAAA,EACvD;AAAA,EAEA,WAAA,CACE,OAAA,GAA6C,EAAC,EAC9C,gBAAA,GAAmD;AAAA,IACjD,aAAA,EAAe,IAAA;AAAA;AAAA,IACf,MAAM,MAAM,CAAA;AAAA;AAAA,IACZ,aAAA,EAAe;AAAA;AAAA,KAEjB,gBAAA,GAA+D;AAAA,IAC7D,aAAA,EAAe,GAAA;AAAA;AAAA,IACf,MAAM,MAAM,CAAA;AAAA;AAAA,IACZ,aAAA,EAAe;AAAA;AAAA,GACjB,EACA;AACA,IAAA,MAAM,SAAA,GAAY,IAAI,kBAAA,CAAmB,OAAO,CAAA;AAChD,IAAA,MAAM,aAAA,GACJ,gBAAA,CAAiB,aAAA,IAAiB,gBAAA,CAAiB,aAAA,IAAiB,EAAA;AAEtE,IAAA,KAAA;AAAA,MACE;AAAA,QACE,SAAA,EAAW,OAAO,KAAA,EAAO,UAAA,KAAe;AACtC,UAAA,IAAI;AACF,YAAA,IAAI,WAAA,GAAc,CAAA;AAElB,YAAA,KAAA,MAAW,MAAA,IAAU,UAAU,QAAA,CAAS,KAAA,EAAO,EAAE,MAAA,EAAQ,IAAA,EAAM,CAAA,EAAG;AAChE,cAAA,UAAA,CAAW,QAAQ,MAAM,CAAA;AACzB,cAAA,WAAA,EAAA;AAGA,cAAA,IACE,WAAA,GAAc,kBAAkB,CAAA,IAChC,UAAA,CAAW,gBAAgB,IAAA,IAC3B,UAAA,CAAW,eAAe,CAAA,EAC1B;AAEA,gBAAA,MAAM,KAAK,gBAAA,EAAiB;AAAA,cAC9B;AAAA,YACF;AAAA,UACF,SAAS,KAAA,EAAO;AACd,YAAA,UAAA,CAAW,MAAM,KAAK,CAAA;AAAA,UACxB;AAAA,QACF,CAAA;AAAA,QACA,KAAA,EAAO,OAAO,UAAA,KAAe;AAC3B,UAAA,IAAI;AACF,YAAA,IAAI,WAAA,GAAc,CAAA;AAElB,YAAA,KAAA,MAAW,MAAA,IAAU,SAAA,CAAU,QAAA,EAAS,EAAG;AACzC,cAAA,UAAA,CAAW,QAAQ,MAAM,CAAA;AACzB,cAAA,WAAA,EAAA;AAGA,cAAA,IACE,WAAA,GAAc,kBAAkB,CAAA,IAChC,UAAA,CAAW,gBAAgB,IAAA,IAC3B,UAAA,CAAW,eAAe,CAAA,EAC1B;AACA,gBAAA,MAAM,KAAK,gBAAA,EAAiB;AAAA,cAC9B;AAAA,YACF;AAAA,UACF,SAAS,KAAA,EAAO;AACd,YAAA,UAAA,CAAW,MAAM,KAAK,CAAA;AAAA,UACxB;AAAA,QACF;AAAA,OACF;AAAA,MACA,gBAAA;AAAA,MACA;AAAA,KACF;AACA,IAAA,IAAA,CAAK,SAAA,GAAY,SAAA;AAAA,EACnB;AACF;;;;"}
+{"version":3,"file":"CSVRecordAssemblerTransformer.js","sources":["../src/CSVRecordAssemblerTransformer.ts"],"sourcesContent":["import { CSVRecordAssembler } from \"./CSVRecordAssembler.ts\";\nimport type {\n  CSVRecord,\n  CSVRecordAssemblerOptions,\n  Token,\n} from \"./common/types.ts\";\n\n/**\n * Default queuing strategy for the writable side (token input).\n * @internal\n */\nconst DEFAULT_WRITABLE_STRATEGY = new CountQueuingStrategy({\n  highWaterMark: 1024, // 1024 tokens\n});\n\n/**\n * Default queuing strategy for the readable side (record output).\n * @internal\n */\nconst DEFAULT_READABLE_STRATEGY = new CountQueuingStrategy({\n  highWaterMark: 256, // 256 records\n});\n\n/**\n * A transform stream that converts a stream of tokens into a stream of CSV records.\n *\n * @template Header The type of the header row.\n * @param options - CSV-specific options (header, maxFieldCount, checkInterval, etc.)\n * @param writableStrategy - Strategy for the writable side (default: `{ highWaterMark: 1024, size: () => 1 }`)\n * @param readableStrategy - Strategy for the readable side (default: `{ highWaterMark: 256, size: () => 1 }`)\n *\n * @category Low-level API\n *\n * @remarks\n * Follows the Web Streams API pattern where queuing strategies are passed as\n * constructor arguments, similar to the standard `TransformStream`.\n *\n * **Default Queuing Strategy:**\n * - Writable side: Counts each token as 1. Default highWaterMark is 1024 tokens.\n * - Readable side: Counts each record as 1. Default highWaterMark is 256 records.\n *\n * **Backpressure Handling:**\n * The transformer monitors `controller.desiredSize` and yields to the event loop when backpressure\n * is detected (desiredSize ≤ 0). This prevents blocking the main thread during heavy processing\n * and allows the downstream consumer to catch up.\n *\n * These defaults are starting points based on data flow characteristics, not empirical benchmarks.\n * Optimal values depend on your runtime environment, data size, and performance requirements.\n *\n * @example Parse a CSV with headers by data\n *  ```ts\n * new ReadableStream({\n *   start(controller) {\n *     controller.enqueue(\"name,age\\r\\n\");\n *     controller.enqueue(\"Alice,20\\r\\n\");\n *     controller.enqueue(\"Bob,25\\r\\n\");\n *     controller.enqueue(\"Charlie,30\\r\\n\");\n *     controller.close();\n *   })\n *   .pipeThrough(new CSVLexerTransformer())\n *   .pipeThrough(new CSVRecordAssemblerTransformer())\n *   .pipeTo(new WritableStream({ write(row) { console.log(row); }}));\n * // { name: \"Alice\", age: \"20\" }\n * // { name: \"Bob\", age: \"25\" }\n * // { name: \"Charlie\", age: \"30\" }\n * ```\n *\n * @example Parse a CSV with headers by options\n * ```ts\n * new ReadableStream({\n *   start(controller) {\n *     controller.enqueue(\"Alice,20\\r\\n\");\n *     controller.enqueue(\"Bob,25\\r\\n\");\n *     controller.enqueue(\"Charlie,30\\r\\n\");\n *     controller.close();\n *   }\n * })\n * .pipeThrough(new CSVLexerTransformer())\n * .pipeThrough(new CSVRecordAssemblerTransformer({ header: [\"name\", \"age\"] }))\n * .pipeTo(new WritableStream({ write(row) { console.log(row); }}));\n * // { name: \"Alice\", age: \"20\" }\n * // { name: \"Bob\", age: \"25\" }\n * // { name: \"Charlie\", age: \"30\" }\n * ```\n *\n * @example Custom queuing strategies with backpressure tuning\n * ```ts\n * const transformer = new CSVRecordAssemblerTransformer(\n *   {\n *     backpressureCheckInterval: 20  // Check backpressure every 20 records\n *   },\n *   new CountQueuingStrategy({ highWaterMark: 2048 }),  // 2048 tokens\n *   new CountQueuingStrategy({ highWaterMark: 512 })    // 512 records\n * );\n *\n * await tokenStream\n *   .pipeThrough(transformer)\n *   .pipeTo(yourRecordProcessor);\n * ```\n */\nexport class CSVRecordAssemblerTransformer<\n  Header extends ReadonlyArray<string>,\n> extends TransformStream<Token, CSVRecord<Header>> {\n  public readonly assembler: CSVRecordAssembler<Header>;\n\n  /**\n   * Yields to the event loop to allow backpressure handling.\n   * Can be overridden for testing purposes.\n   * @internal\n   */\n  protected async yieldToEventLoop(): Promise<void> {\n    await new Promise((resolve) => setTimeout(resolve, 0));\n  }\n\n  constructor(\n    options: CSVRecordAssemblerOptions<Header> = {},\n    writableStrategy: QueuingStrategy<Token> = DEFAULT_WRITABLE_STRATEGY,\n    readableStrategy: QueuingStrategy<\n      CSVRecord<Header>\n    > = DEFAULT_READABLE_STRATEGY,\n  ) {\n    const assembler = new CSVRecordAssembler(options);\n    const checkInterval = options.backpressureCheckInterval ?? 10;\n\n    super(\n      {\n        transform: async (token, controller) => {\n          try {\n            let recordCount = 0;\n            // Pass single token directly to assemble (no array creation)\n            for (const record of assembler.assemble(token, { stream: true })) {\n              controller.enqueue(record);\n              recordCount++;\n\n              // Check backpressure periodically based on checkInterval\n              if (\n                recordCount % checkInterval === 0 &&\n                controller.desiredSize !== null &&\n                controller.desiredSize <= 0\n              ) {\n                // Yield to event loop when backpressure is detected\n                await this.yieldToEventLoop();\n              }\n            }\n          } catch (error) {\n            controller.error(error);\n          }\n        },\n        flush: async (controller) => {\n          try {\n            let recordCount = 0;\n            // Call assemble without arguments to flush\n            for (const record of assembler.assemble()) {\n              controller.enqueue(record);\n              recordCount++;\n\n              // Check backpressure periodically based on checkInterval\n              if (\n                recordCount % checkInterval === 0 &&\n                controller.desiredSize !== null &&\n                controller.desiredSize <= 0\n              ) {\n                await this.yieldToEventLoop();\n              }\n            }\n          } catch (error) {\n            controller.error(error);\n          }\n        },\n      },\n      writableStrategy,\n      readableStrategy,\n    );\n    this.assembler = assembler;\n  }\n}\n"],"names":[],"mappings":";;AAWA,MAAM,yBAAA,GAA4B,IAAI,oBAAA,CAAqB;AAAA,EACzD,aAAA,EAAe;AAAA;AACjB,CAAC,CAAA;AAMD,MAAM,yBAAA,GAA4B,IAAI,oBAAA,CAAqB;AAAA,EACzD,aAAA,EAAe;AAAA;AACjB,CAAC,CAAA;AA+EM,MAAM,sCAEH,eAAA,CAA0C;AAAA,EAClC,SAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOhB,MAAgB,gBAAA,GAAkC;AAChD,IAAA,MAAM,IAAI,OAAA,CAAQ,CAAC,YAAY,UAAA,CAAW,OAAA,EAAS,CAAC,CAAC,CAAA;AAAA,EACvD;AAAA,EAEA,YACE,OAAA,GAA6C,IAC7C,gBAAA,GAA2C,yBAAA,EAC3C,mBAEI,yBAAA,EACJ;AACA,IAAA,MAAM,SAAA,GAAY,IAAI,kBAAA,CAAmB,OAAO,CAAA;AAChD,IAAA,MAAM,aAAA,GAAgB,QAAQ,yBAAA,IAA6B,EAAA;AAE3D,IAAA,KAAA;AAAA,MACE;AAAA,QACE,SAAA,EAAW,OAAO,KAAA,EAAO,UAAA,KAAe;AACtC,UAAA,IAAI;AACF,YAAA,IAAI,WAAA,GAAc,CAAA;AAElB,YAAA,KAAA,MAAW,MAAA,IAAU,UAAU,QAAA,CAAS,KAAA,EAAO,EAAE,MAAA,EAAQ,IAAA,EAAM,CAAA,EAAG;AAChE,cAAA,UAAA,CAAW,QAAQ,MAAM,CAAA;AACzB,cAAA,WAAA,EAAA;AAGA,cAAA,IACE,WAAA,GAAc,kBAAkB,CAAA,IAChC,UAAA,CAAW,gBAAgB,IAAA,IAC3B,UAAA,CAAW,eAAe,CAAA,EAC1B;AAEA,gBAAA,MAAM,KAAK,gBAAA,EAAiB;AAAA,cAC9B;AAAA,YACF;AAAA,UACF,SAAS,KAAA,EAAO;AACd,YAAA,UAAA,CAAW,MAAM,KAAK,CAAA;AAAA,UACxB;AAAA,QACF,CAAA;AAAA,QACA,KAAA,EAAO,OAAO,UAAA,KAAe;AAC3B,UAAA,IAAI;AACF,YAAA,IAAI,WAAA,GAAc,CAAA;AAElB,YAAA,KAAA,MAAW,MAAA,IAAU,SAAA,CAAU,QAAA,EAAS,EAAG;AACzC,cAAA,UAAA,CAAW,QAAQ,MAAM,CAAA;AACzB,cAAA,WAAA,EAAA;AAGA,cAAA,IACE,WAAA,GAAc,kBAAkB,CAAA,IAChC,UAAA,CAAW,gBAAgB,IAAA,IAC3B,UAAA,CAAW,eAAe,CAAA,EAC1B;AACA,gBAAA,MAAM,KAAK,gBAAA,EAAiB;AAAA,cAC9B;AAAA,YACF;AAAA,UACF,SAAS,KAAA,EAAO;AACd,YAAA,UAAA,CAAW,MAAM,KAAK,CAAA;AAAA,UACxB;AAAA,QACF;AAAA,OACF;AAAA,MACA,gBAAA;AAAA,MACA;AAAA,KACF;AACA,IAAA,IAAA,CAAK,SAAA,GAAY,SAAA;AAAA,EACnB;AACF;;;;"}

package/dist/assertCommonOptions.d.ts

@@ -18,4 +18,4 @@ import { CommonOptions } from './common/types.ts';
  * @throws {RangeError} If any required property is missing or if the delimiter is the same as the quotation.
  * @throws {TypeError} If any required property is not a string.
  */
-export declare function assertCommonOptions<Delimiter extends string, Quotation extends string>(options: Required<CommonOptions<Delimiter, Quotation>>): asserts options is Required<CommonOptions<Delimiter, Quotation>>;
+export declare function assertCommonOptions<Delimiter extends string, Quotation extends string>(options: Required<Omit<CommonOptions<Delimiter, Quotation>, "source">>): asserts options is Required<Omit<CommonOptions<Delimiter, Quotation>, "source">>;

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'`.
@@ -291,12 +355,64 @@ export interface BinaryOptions {
      * ```
      */
     allowExperimentalCompressions?: boolean;
+    /**
+     * Allow non-standard character encodings not in the common charset list.
+     *
+     * @remarks
+     * When `true`, charset values from Content-Type headers that are not in the
+     * default supported list will be passed to the runtime's TextDecoder without
+     * validation. This allows using character encodings that may not be universally
+     * supported across all environments.
+     *
+     * ### Default Supported Charsets (commonly used)
+     *
+     * When `false` (default), only commonly used charsets are allowed, including:
+     * - **UTF**: `utf-8`, `utf-16le`, `utf-16be`
+     * - **ISO-8859**: `iso-8859-1` through `iso-8859-16`
+     * - **Windows**: `windows-1250` through `windows-1258`
+     * - **Asian**: `shift_jis`, `euc-jp`, `gb18030`, `euc-kr`, etc.
+     *
+     * ### Security Considerations
+     *
+     * **Use with caution**: Enabling this bypasses library validation and relies entirely
+     * on runtime error handling. Invalid or malicious charset values could cause:
+     * - Runtime exceptions from TextDecoder
+     * - Unexpected character decoding behavior
+     * - Potential security vulnerabilities
+     *
+     * It's recommended to validate charset values against your expected inputs before
+     * enabling this option.
+     *
+     * @default false
+     *
+     * @example
+     * ```ts
+     * // Safe mode (default): Only commonly supported charsets
+     * const response = await fetch('data.csv');
+     * await parse(response); // charset must be in SUPPORTED_CHARSETS
+     *
+     * // Allow non-standard charset
+     * const response = await fetch('data.csv'); // Content-Type: text/csv; charset=custom-encoding
+     * await parse(response, { allowNonStandardCharsets: true });
+     * // ⚠️ May throw error if runtime doesn't support the charset
+     * ```
+     */
+    allowNonStandardCharsets?: boolean;
 }
 /**
  * CSV Lexer Transformer Options.
  * @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.
@@ -309,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.
      *
@@ -343,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.
@@ -378,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 } })
+     * ```
+     */
+    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?: boolean;
+    worker: true;
     /**
      * Custom Worker URL.
-     * Only applicable when `worker: true`.
      *
      * If not provided, uses the bundled worker.
      *
@@ -418,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.
@@ -455,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
@@ -520,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
@@ -578,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.
  *
@@ -646,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;;;;"}